Adding & Managing Identities

Comprehensive guide to syncing Identities and Integrations with the Captain Data API v4.

The first step in using the Captain Data API (v4) to manage identities is to synchronize your SaaS users as identities with your Captain Data workspace.

Here’s a quick recap of the ways Captain Data can adapt to your needs:

1. White Label – Fully branded solutions where Captain Data runs in the background, allowing your brand to take the spotlight.
2. White Label — Stealth Mode – Run Captain Data’s API with rented LinkedIn accounts—no Chrome Extension required. Check out this article for more information: When to Sync Identities vs. Use Rented LinkedIn Accounts
3. Grey Label – Combine Captain Data’s Chrome Extension with shared accounts, utilizing our branded Captain Data connection flow.

When integrating your SaaS with Captain Data, it’s important to understand the distinction between Identities and Integrations.

• Identities: Each user on your SaaS corresponds to an identity in Captain Data. Think of a identity as a license that enables automation for that individual.
• Integrations: Integrations are the specific integrations (like LinkedIn) attached to an identity, allowing them to run automations on specific platforms.

1. Create an Identity

To enable automation for an Identity, create the identity by sending a POST request to the Create an Identity endpoint:

curl --request POST \
  --url https://api.captaindata.com/v4/identities \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your_api_key>' \
  --data '{
  "name": "John Doe or a reference for your identity",
  "timezone": "Europe/Paris"
}'

name · string

A name that allows you to identify the Identity: it can be the full name of the Identity or an internal reference (or both!) at your convenience.

timezone · string

The Identity’s timezone.

The timezone field provisions a proxy IP matching that timezone/country. This needs to match the location where you log into your LinkedIn account to avoid restrictions.

When using a VPN, either: 1. Log out of your VPN before accessing social media, or 2. Ensure the “timezone” you send matches the country of the VPN IP address.

Save the Identity’s uid

Once the request is successful, Captain Data will return an Identity’s uid.

Save this as identity_uid in your own user database - you’ll need it for:

• Connecting integrations for this Identity
• Launching actions, via the identity_ids field

💡 When launching an action, always pass the Identity’s uid via the identity_ids field. You do not need to pass the Integration’s UID.

2. Connect an Identity’s Integration

To run most automations, your identities must be linked to the platform(s) they’ll act on, like LinkedIn. This section walks you through creating an identity and connecting the necessary integrations using Captain Data’s API.

Once you have created an identity, the next step is to attach an integration. This integration enables the identity to automate specific platforms, like LinkedIn, through Captain Data.

Request Body

To create or update an integration, use the POST method for the Connect an Identity’s Integration endpoint. Here’s an example for a COOKIES integration type (like LinkedIn):

curl --request POST \
  --url https://api.captaindata.com/v4/identities/{identity_uid}/integrations/linkedin \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your_api_key>' \
  --data '{
  "account_name": "LinkedIn Account #1",
  "auth_data": {
    "cookies": {
      "li_at": "<li_at_token>",
      "li_a": "<li_a_token>"
    }
  }
}'

account_name · string

Name of the LinkedIn account, e.g. “LinkedIn Account #1”. It’s generally the User’s full_name or email.

auth_data.cookies · object

For COOKIES integration types, provide authentication cookies here.

Important note: If you’re connecting an account for LinkedIn Sales Navigator, you need to send both cookies. If you don’t include the li_a token, the connection may not work properly with LinkedIn Sales Navigator. Including the li_a token will also speed up account synchronization.

Supported Authentication Types

Captain Data supports the following integration types:

• COOKIES
• BASIC
• OAUTH
• APIKEY

Each type may require a slightly different request body. The example provided is for a COOKIES integration.

Save the Integration’s uid

Once the request is successful, Captain Data will return an Integration’s uid.

Save this uid in your own database model if you need to update or remove it later, for example.

Native LinkedIn Authentication

You can also authenticate LinkedIn accounts using email and password credentials. This method uses Captain Data’s native LinkedIn authentication system.

Here’s an example request using the Connect a LinkedIn Account (Username/Password) endpoint:

curl --request POST \
  --url https://api.captaindata.com/v4/identities/{identity_uid}/integrations/linkedin \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "auth_data": {
    "basic": {
      "username": "[e-mail]",
      "password": "********"
    }
  }
}'

Native LinkedIn Login Link

To make integration setup seamless for your users, we handle all the authentication complexity for you. Instead of building your own login forms and credential handling, we provide unique, time-limited URLs (valid for 48 hours) that let your users connect their accounts securely.

These links work with supported integrations like LinkedIn - all without needing a browser extension or custom form handling.

When you create an Identity through our Identity creation endpoint, you’ll receive these login links in the response:

{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2023-10-01T12:00:00Z",
  "workspace_uid": "5678e456-e89b-12d3-a456-426614174001",
  "name": "John Doe",
  "timezone": "Europe/Paris",
  "integrations": [],
  "identity_login_links": {
    "linkedin": "https://app.captaindata.com/identities/linkedin/login?token=XXXXXX"
  }
}

You can share the login URL (https://app.captaindata.com/identities/linkedin/login?token=XXXXXX) via email or embed it directly in your product interface as a button or link. When clicked, it will take users to our secure, white-labeled authentication page where they can complete the LinkedIn connection process.

This feature eliminates the need for browser extensions or custom login forms. Users can securely connect their LinkedIn accounts by simply visiting the provided login link, which works across all browsers and supports any security method (including SMS, authenticator apps, and in-app confirmations).

Assistant

Responses are generated using AI and may contain mistakes.