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.

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. Generate and copy your personal API key

Keep your API key secure—treat it like a password. Each API key is tied to your specific user 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 Profile”)
  2. Note the Action’s unique identifier from its URL
  3. Use the Action’s identifier to make API calls

​
Prerequisites: Users & Integrations

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

To set this up:

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

Some Actions don’t require Users or Integrations. Check if the Action’s payload includes integration_users - if it does, you’ll need to set up Users and connect their integration 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": {},
  "integration_users": [
    "<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.