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 managed LinkedIn accounts—no Chrome Extension required. Check out this article for more information: LinkedIn Identities Options: Sync, Rent, or Use Managed
  3. Grey Label – Combine Captain Data’s Chrome Extension with shared accounts, utilizing our branded Captain Data connection flow.
Quick Start Option: If you want to get started immediately without managing identities and integrations, you can use Managed Mode which uses Captain Data’s pre-configured accounts (1.5× credit cost).For comprehensive details about identity modes, see Identity Modes: Direct, Auto, and Managed.
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.
Captain Data supports the canonical IANA time zones, as defined by the tz database. Only canonical names are accepted. Deprecated or alias entries are currently not supported.Example: “Europe/Kiev” is deprecated and has been replaced by “Europe/Kyiv”, which is the valid canonical identifier. Deprecated names are maintained in the IANA backward zone file for legacy compatibility but should not be used.

​
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.

​
Identity Modes

Captain Data supports three identity modes to control how accounts are used for action execution:

​
Direct Mode

Use specific identities for precise control: 
curl --request POST \
  --url 'https://api.captaindata.com/v4/actions/linkedin-extract-people/run/live' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "identity_mode": "direct",
    "identity_ids": ["identity-1", "identity-2"]
  }'

​
Auto Mode

Automatic distribution across all available accounts: 
curl --request POST \
  --url 'https://api.captaindata.com/v4/actions/linkedin-extract-people/run/live' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "identity_mode": "auto"
  }'

​
Managed Mode

Use Captain Data’s pre-configured account pool (1.5× credit cost): 
curl --request POST \
  --url 'https://api.captaindata.com/v4/actions/linkedin-extract-people/run/live' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "identity_mode": "managed"
  }'
Managed mode cost: Using identity_mode: "managed" costs 1.5× the standard credit cost but requires no setup.
For detailed comparisons and use case recommendations, see LinkedIn Identities Options: Sync, Rent, or Use Managed.

​
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.

​
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": "[email protected]",
      "password": "********"
    }
  }
}'
Important: we encrypt everything for security reasons.
To simplify integration setup for your users, we handle all authentication complexity automatically. Rather than building custom login forms and managing credentials, we provide secure, time-limited URLs (valid for 48 hours) that enable users to connect their accounts seamlessly. These login links work with supported integrations like LinkedIn without requiring browser extensions or custom form handling. When you create an Identity using 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, users are taken to our secure, white-labeled authentication page to 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 all security methods (including SMS, authenticator apps, and in-app confirmations).