Adding & Managing Users

Comprehensive guide to syncing users and accounts with the Captain Data API.

The first step in using the Captain Data API to manage users is to synchronize your SaaS users 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 Users 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 users and accounts.

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

Once you create a user, you’ll need to attach one or more integration accounts to that user.

White Label

Process to create your Users using our API - White Label

This diagram illustrates the process from user creation on your platform to synchronization with Captain Data.

The user generates a UID on your platform, which you store. They then install your Chrome extension (for example) to capture the necessary cookies. Finally, you make API calls to Captain Data to create both the user and integration accounts.

Ensure that you store the UIDs at each step.

Grey Label

Process to create your Users using our API - Grey Label

This diagram shows the process from creating a user on your platform to syncing their LinkedIn account with us. Store your user UID, then initiate the Add a user and/or Add Integration Account call.

Make sure to set shared_account to true when adding the account.

This lets you generate a link like this: https://app.captaindata.co/integrations/linkedin/accounts/{user_id}.

Share this link with your user, and they will install the Captain Data Chrome Extension to sync their account. Their LinkedIn account will then be linked to their Captain user.

Invalid cookies? For faster cookie updates, resend this link to the owner of the account to refresh cookies instantly.

1. Add or Update a User

To enable automation for a user, create the user by sending a POST request to the Create or Update a User endpoint:

https://api.captaindata.co/v3/users

Request Body

Here’s an example of the request body:

{
  "email": "[e-mail]",
  "full_name": "Test Test",
  "country": "FR",
  "uid": "Provide a UID to update an existing user."
}

Explanation of the Fields

Field	Required?	Description
email	Optional	The user’s email address.
full_name	Required	The user’s full name.
country	Required	ISO 3166-1 alpha-2 code (e.g., US, FR, DE). Used to provision a proxy IP within this country.
uid	Required to Update operation only	Leave this field empty to create a new user. Provide a UID to update an existing user.

Always provide a “country” when creating a user. This allows Captain Data to provision a proxy IP within the selected country and attach it to the user.

To avoid restrictions on social media platforms (like LinkedIn), ensure the “country” matches the physical location from which the social media account is accessed. If using a VPN, make sure to match the location of the VPN with the “country” you select.

If this step is missed, certain social media platforms may flag or block the connection.

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

Prohibited Country Codes

You can use any ISO 3166-1 alpha-2 country code except the following:

"MG","RE","CI", "NA", "CV", "MU", "HN", "UY", "XK", "GN", "UA", "BB", "PF", "QA", "KY", "LY", "LB", "VE", "UG", "CH", "PK"

These country codes are restricted to ensure compliance with platform requirements and maintain secure automation.

Save the user_uid

Once the request is successful, Captain Data will return a user_uid.

Save this user_uid in your own user database so you can link it to the accounts you create later. This user_uid is required to create integration accounts for this user.

2. Add or Update an Integration Account

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

To create or update an integration account, use the POST method for the Add or Update Integration Account endpoint:

Request Body

Here’s an example for a COOKIES integration type (like LinkedIn):

{
  "account": {
    "uid": "12345-abcde",
    "name": "New account",
    "cookies": {
      "li_at": "YOUR_SESSION_COOKIE"
    },
    "user_uid": "67890-xyz"
  },
  "resume_paused_jobs": false,
  "shared_account": false,
  "retrieve_ip": false
}

Explanation of the Fields

Field	Required?	Description
account.uid	Optional	If provided, updates an existing account. If empty, creates a new account.
account.name	Required	Name of the integration account (e.g., “LinkedIn Account 1”).
account.cookies	Required (if COOKIES)	For COOKIES integration types, provide authentication cookies here.
account.user_uid	Required	The user_uid linked to this account (from the previous step).
resume_paused_jobs	Optional	Resumes any paused jobs once the cookie is valid again. Default: false.
shared_account	Optional	Boolean flag to indicate if you need to create a shared account. Default: false.
retrieve_ip	Optional	Boolean flag to retrieve IP information. Default: false.

Important note: If you’re creating an account for LinkedIn Sales Navigator, you need to send both cookies:

"cookies": {
  "li_at": "YOUR_SESSION_COOKIE",
  "li_a": "YOUR_SALES_NAV_COOKIE"
}

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 (like LinkedIn)
• OAUTH
• APIKEY
• BASIC

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

Save the account_uid

Once the request is successful, Captain Data will return an account_uid.

Save this account_uid in your own database model for the user. You will need this account_uid to launch jobs for this account.

3. Launch a Workflow

With the account_uid in place, you can now trigger automations.

To do so, use the POST method for the Launch a Workflow endpoint.

https://api.captaindata.co/v3/workflows/:workflow_uid/launch

You will need to pass the account_uid of the integration account for which you want to launch the workflow. This enables you to run automations for the user using the accounts they have connected.

For example in a step:

{
  "accounts": [ {{ account_uid }}],
  "accounts_rotation_enabled": false,
  "parameters": {},
  "output_column": null,
  "step_uid": "xxxxxx-xxxxx-451f-ac94-2b41972ec6a7"
}

Shared Accounts

A Shared Account allows external users to connect their accounts via a Captain Data shared link, which grants them access to sync their credentials.

Unlike regular users, Shared Accounts do not have access to the Captain Data workspace, but they can still be used for automations via the API.

Shared Accounts must be defined during the creation process (Add) and cannot be modified later. To create an external user as a Shared Account and provide them with a Captain Data shared link to update or refresh their account, include the following payload:

{
	"account": { ... },
	"shared_account": true
}

4. Updating Accounts

Don’t skip this step if you’re automating LinkedIn! For LinkedIn’s automation, it’s essential to keep user cookies up-to-date to avoid service disruptions.

How to Update an Account

Normally, you’d use Captain Data’s Chrome Extension to refresh cookies automatically.

If you’re building your own Chrome Extension, you must ensure that user cookies are updated regularly to maintain uninterrupted service.

👉 Follow our guide on Building Chrome Extensions Best Practices for detailed instructions.

How to Update Cookies Using the API

To update cookies or other account details, you’ll use the same POST method as before:

Add or Update Integration Account

https://api.captaindata.co/v3/integrations/:integration_uid/accounts

How it works:

1. Pass the existing account_uid in the request body.
2. Provide the new cookie value or any updated field.
3. Captain Data will recognize that the account exists and update the stored information accordingly.

Here’s an example of how to update the cookie for a LinkedIn account:

{
  "account": {
    "uid": "12345-abcde",
    "name": "LinkedIn Account",
    "cookies": {
      "li_at": "NEW_SESSION_COOKIE_VALUE"
    }
  }
}

Don’t forget the cookie li_a if you’re working with Sales Navigator.

Key Notes:

• Use the existing account_uid to update the account.
• If you only need to update cookies (like li_at), you can leave other fields unchanged.
• For LinkedIn Sales Navigator, also ensure you update the li_a cookie to maintain the connection.

How-to setup accounts update using a Chrome a Extension

5. Deleting Accounts

If you delete a user from your app, remember to also remove them from Captain Data.

This helps prevent unnecessary charges and keeps your user data in sync.

To delete a user, use the DELETE method on the Remove User endpoint:

DELETE https://api.captaindata.co/v3/users/:user_uid

Key Notes:

• This action will completely remove the user and any linked integration accounts.
• Make sure to remove users from both your app and Captain Data to keep everything in sync.
• Deleting users also prevents unwanted billing charges related to user licenses.

6. Enabling auto-manage & billing with the API

You can automate user license provisioning using Captain Data’s auto-manage feature.

This allows you to dynamically add or remove users via the API and automatically manage subscription upgrades.

1. Go to Settings: My Account > Users > Settings
2. Check the box: “Enable users management from the API”

How it works:

• Once enabled, any new user added via the API will automatically trigger an update to your subscription plan.
• The maximum user limit is set to 0 by default, which allows for an unlimited number of users.
• To avoid unexpected subscription increases, you can set a maximum number of users in the settings.

If you activate this feature, new users will be automatically billed to your subscription.

Example Use Case

Imagine you have a SaaS app where you dynamically add users.

When a new user signs up, you can:

1. Call Captain Data’s API to provision a new user.
2. This feature automatically increase the number of Captain Data users in your subscription plan.
3. Should you remove the user for inactivity, this will decrease the number of users (at the end of the billing cycle)

This ensures your app and Captain Data stay in sync.

Important Billing Note

Enabling auto-manage will dynamically increase your subscription plan as you add users.

To avoid unexpected charges, set a limit for the maximum number of workspace users. This can be managed under My Account > Users > Settings.