Introduction

API Reference Version 4

Welcome to Captain Data API v4, which allows you to automate Actions in Real-Time. You can also manage Identities and their Integrations. If you encounter any issues using this API, feel free to reach out at [e-mail].

If you’re new to Captain Data, we strongly recommend reviewing the following resources before diving into the API:

• Quickstart – A brief overview of how to use the API.
• Core Concepts – A description of core objects and how to interact with them.

Authentication

To authorize requests, you need to add the following header X-API-Key: <your_api_key> to all API requests (case insensitive). Here’s an example of a request to the API:

curl --location 'https://api.captaindata.com/v4/workspaces' \
--header 'X-API-Key: <your_api_key>'

All subsequent examples will use this header as part of the request.

To get your API Key, go to Developer Settings and copy the appropriate values.

Each user of your workspace has their own unique API Key that is tied to their account. API Keys are not shared across the workspace.

Playground

Each API endpoint has an interactive playground where you can test requests directly.

SDK

Starting May 2025, we’re thrilled to announce Captain Data’s first TypeScript SDK. This type-safe SDK offers a streamlined way to interact with our API through a single CaptainData class. It handles authentication and provides access to Core endpoints and integrations including LinkedIn and Sales Navigator.

Migrate from v3

Checkout Migrate from v3 for a complete migration guide.

If you’re coming from Captain Data v3, a lot has changed. We’re switching from a Batch-approach with Runs and Webhooks, to a Real-Time approach. This means when you query the API, you get an instant result without needing to create Workflows.

Here’s what’s changing 👇

Previous Approach (v3)

• Users created multi-step workflows through the UI
• Workflows were triggered by CRON jobs or webhooks
• API calls launched workflows with asynchronous results

New Approach (v4)

• ✅ 1. Launched March 2025: Real-Time API → Get instant results with a single API call
• ✅ 2. Launched May 2025: Asynchronous Processing → Process large batches of data with webhook notifications
• ✅ 3. Launched June 2025: Scheduled Processing → Automate your data processing with configurable schedules (CRON)

Real-Time API Limitations

The real-time API offers improved speed and simplicity, but comes with some constraints:

Real-Time Limitation	What This Means
No Multi-Step Actions	❌ You cannot chain actions (e.g., “Search → Enrich → Message”) in one call. This logic must be handled in your code.
No CRON/Scheduling	❌ You need to implement your own scheduling and retry mechanisms.
No Queuing	❌ When rate limits are hit, requests fail immediately rather than being queued.
Fixed Rate Limits	✅ You must check your usage via an API endpoint instead of relying on automatic queue management.
Concurrency Limits	✅ For LinkedIn-related actions, we limit processing to one request per account to prevent detection.
Single Input Processing	✅ Each API call can only process one input, requiring different handling for bulk operations.

Async Mode

Async Mode provides solutions for several of these limitations:

Real-Time Limitation	Async Mode Solution
No Multi-Step Flows	❌ Will remain as a limitation
No Scheduling	✅ Will support CRON-based scheduling through dedicated Schedule Mode
No Queuing	✅ Will automatically queue requests when rate limits are reached
Fixed Rate Limits	✅ Will handle batching and time distribution automatically
Concurrency	✅ Will enable safe parallel processing
Single Input	✅ Will support bulk processing with thousands of records per API call

Schedule Mode

The Schedule Mode enables automated data processing through configurable CRON schedules, allowing you to set up recurring tasks without manual intervention.

It also allows to postpone an execution or a CRON schedule at a specific date in the future.