> ## Documentation Index
> Fetch the complete documentation index at: https://v3.captaindata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Adding & Managing Users
> Comprehensive guide to syncing users and accounts with the Captain Data API v3.
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 Identities vs. Use Rented LinkedIn Accounts](/v3/users-accounts/users-vs-rented-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
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
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](/v3/api-reference/users/create-update-user) endpoint:
```bash
https://api.captaindata.co/v3/users
```
### **Request Body**
Here’s an example of the request body:
```json
{
"email": "test@test.co",
"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](https://www.iban.com/country-codes) 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](/v3/api-reference/integrations/add-update-account) endpoint:
### **Request Body**
Here’s an example for a **COOKIES** integration type (like LinkedIn):
```json
{
"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:
```json
"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](/v3/api-reference/workflows/launch-workflow) endpoint.
```bash
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:
```json
{
"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:
```json
{
"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**](/v3/linkedin/chrome-extension) 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](/v3/api-reference/integrations/add-update-account)
```bash
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:
```json
{
"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.
## **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](/v3/api-reference/users/remove-user) endpoint:
```bash
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](https://app.captaindata.co/settings/users/parameters)
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.
### **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](https://app.captaindata.co/settings/users/parameters).