If you’re coming from Captain Data v3, we’ve moved from batch processing to real-time responses - you’ll get instant results with each API call, no workflows needed. Need the v3 documentation? Visit our v3 Quickstart. For migration assistance, check our v3 to v4 Migration Guide.

Important: API Keys and Workspaces from v3 are not compatible with v4. You’ll need to create a new account and generate a new API key to use v4.

This guide will help you use our API to extract and enrich data through our Actions. Follow the steps below to get up and running quickly.

​
1. Introduction to the Captain Data API

The Captain Data API allows you to extract data and enrich your existing datasets through our Actions. Whether you’re building custom integrations or scaling operations, the API offers flexibility and efficiency.

For more details, see our API Reference Documentation.

​
2. Setting Up the API

Follow these steps to get your API Key:

  1. Log in to your Captain Data account
  2. Navigate to the Developer Settings section
  3. Copy your personal API key

Keep your API key secure—treat it like a password. Each API key is tied to your specific member’s account.

​
3. Using Actions

​
Understanding Actions

An Action is a specific operation that can extract data, enrich existing data, or automate interactions. Actions can perform tasks like sending connection requests, sending messages, extracting message histories, and much more - all in real-time with immediate results.

​
How to Use an Action

  1. Browse the Actions Library to find the Action you need, e.g. Extract LinkedIn People
  2. Note the Action’s unique identifier from its URL
  3. Use the Action’s identifier to make API calls

​
Prerequisites: Identities & Integrations

Most Actions, especially those automating LinkedIn, require one or more Identities with connected Integrations. You’ll know you need these when you see identity_ids in the API payload.

To set this up:

  1. First, Create an Identity to represent your end-user or AI agent
  2. Then, Connect an Integration for that identity (e.g., connect their LinkedIn account)

Some Actions don’t require Identities or Integrations. Check the Action’s payload for identity_ids - if present, you’ll need to set up Identities and connect their integrations first.

For LinkedIn specifically, you can either:

​
Making API Calls

Each Action accepts a single input and returns results in real-time. The response format depends on the Action type:

  • Enrichment Actions: Generally return one enriched result per input
  • Search Actions: Can return multiple results, with pagination support for larger result sets

Example of an API call:

curl --request POST \
  --url https://api.captaindata.com/v4/actions/linkedin-search-people/run/live \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "parameters": {},
  "identity_ids": [
    "<string>"
  ],
  "input": {
    "linkedin_people_search_url": "https://www.linkedin.com/search/results/people/?keywords=software%20engineer"
  }
}'

The response will be an array of LinkedIn profiles matching your search criteria:

[
  {
    "full_name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "job_title": "Senior Software Engineer",
    "company_name": "Tech Company",
    "headline": "Software Engineer | Full Stack Developer",
    "location": "San Francisco Bay Area",
    "linkedin_profile_url": "https://www.linkedin.com/in/johndoe",
    "profile_image_url": "https://example.com/profile.jpg",
    "linkedin_profile_id": "123456789",
    "connection_degree": "2nd",
    "current_title": "Senior Software Engineer at Tech Company"
  }
]

​
4. Error Handling

The API uses a consistent error response format across all endpoints. When an error occurs, you’ll receive a response with the following structure:

{
  "error_label": "INVALID_INPUT",
  "error_scope": "input",
  "error_ref": "ERR-12345",
  "message": "The provided input is invalid. Please check your request and try again.",
  "status_code": 400,
  "params": {}
}

Each error response includes:

  • error_label: A machine-readable identifier for the error type
  • error_scope: Indicates which part of the request caused the error (e.g., “input”, “auth”, “server”)
  • error_ref: A unique reference code for tracking and debugging
  • message: A human-readable description of the error
  • status_code: The HTTP status code
  • params: Additional error parameters (if any)

Common HTTP status codes:

  • 200: The request was successful (some API calls may return 201 instead)
  • 400: Bad Request - Invalid input or parameters
  • 401: Unauthorized - Invalid or missing API key
  • 403: Forbidden - Insufficient permissions
  • 404: Not Found - Resource doesn’t exist
  • 500: Internal Server Error - Server-side issue

Always check the error_label and error_scope fields to programmatically handle different types of errors in your application.

If you encounter an unusual error, such as a 500 or 503, feel free to reach out! These are internal errors on our end, and we’re happy to help resolve them.

If you’re coming from Captain Data v3, we’ve moved from batch processing to real-time responses - you’ll get instant results with each API call, no workflows needed. Need the v3 documentation? Visit our v3 Quickstart. For migration assistance, check our v3 to v4 Migration Guide.

Important: API Keys and Workspaces from v3 are not compatible with v4. You’ll need to create a new account and generate a new API key to use v4.

This guide will help you use our API to extract and enrich data through our Actions. Follow the steps below to get up and running quickly.

​
1. Introduction to the Captain Data API

The Captain Data API allows you to extract data and enrich your existing datasets through our Actions. Whether you’re building custom integrations or scaling operations, the API offers flexibility and efficiency.

For more details, see our API Reference Documentation.

​
2. Setting Up the API

Follow these steps to get your API Key:

  1. Log in to your Captain Data account
  2. Navigate to the Developer Settings section
  3. Copy your personal API key

Keep your API key secure—treat it like a password. Each API key is tied to your specific member’s account.

​
3. Using Actions

​
Understanding Actions

An Action is a specific operation that can extract data, enrich existing data, or automate interactions. Actions can perform tasks like sending connection requests, sending messages, extracting message histories, and much more - all in real-time with immediate results.

​
How to Use an Action

  1. Browse the Actions Library to find the Action you need, e.g. Extract LinkedIn People
  2. Note the Action’s unique identifier from its URL
  3. Use the Action’s identifier to make API calls

​
Prerequisites: Identities & Integrations

Most Actions, especially those automating LinkedIn, require one or more Identities with connected Integrations. You’ll know you need these when you see identity_ids in the API payload.

To set this up:

  1. First, Create an Identity to represent your end-user or AI agent
  2. Then, Connect an Integration for that identity (e.g., connect their LinkedIn account)

Some Actions don’t require Identities or Integrations. Check the Action’s payload for identity_ids - if present, you’ll need to set up Identities and connect their integrations first.

For LinkedIn specifically, you can either:

​
Making API Calls

Each Action accepts a single input and returns results in real-time. The response format depends on the Action type:

  • Enrichment Actions: Generally return one enriched result per input
  • Search Actions: Can return multiple results, with pagination support for larger result sets

Example of an API call:

curl --request POST \
  --url https://api.captaindata.com/v4/actions/linkedin-search-people/run/live \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "parameters": {},
  "identity_ids": [
    "<string>"
  ],
  "input": {
    "linkedin_people_search_url": "https://www.linkedin.com/search/results/people/?keywords=software%20engineer"
  }
}'

The response will be an array of LinkedIn profiles matching your search criteria:

[
  {
    "full_name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "job_title": "Senior Software Engineer",
    "company_name": "Tech Company",
    "headline": "Software Engineer | Full Stack Developer",
    "location": "San Francisco Bay Area",
    "linkedin_profile_url": "https://www.linkedin.com/in/johndoe",
    "profile_image_url": "https://example.com/profile.jpg",
    "linkedin_profile_id": "123456789",
    "connection_degree": "2nd",
    "current_title": "Senior Software Engineer at Tech Company"
  }
]

​
4. Error Handling

The API uses a consistent error response format across all endpoints. When an error occurs, you’ll receive a response with the following structure:

{
  "error_label": "INVALID_INPUT",
  "error_scope": "input",
  "error_ref": "ERR-12345",
  "message": "The provided input is invalid. Please check your request and try again.",
  "status_code": 400,
  "params": {}
}

Each error response includes:

  • error_label: A machine-readable identifier for the error type
  • error_scope: Indicates which part of the request caused the error (e.g., “input”, “auth”, “server”)
  • error_ref: A unique reference code for tracking and debugging
  • message: A human-readable description of the error
  • status_code: The HTTP status code
  • params: Additional error parameters (if any)

Common HTTP status codes:

  • 200: The request was successful (some API calls may return 201 instead)
  • 400: Bad Request - Invalid input or parameters
  • 401: Unauthorized - Invalid or missing API key
  • 403: Forbidden - Insufficient permissions
  • 404: Not Found - Resource doesn’t exist
  • 500: Internal Server Error - Server-side issue

Always check the error_label and error_scope fields to programmatically handle different types of errors in your application.

If you encounter an unusual error, such as a 500 or 503, feel free to reach out! These are internal errors on our end, and we’re happy to help resolve them.