Quickstart
Welcome to Captain Data’s API v4 implementation guide.
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:
- Log in to your Captain Data account
- Navigate to the Developer Settings section
- 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
- Browse the Actions Library to find the Action you need (e.g. “Extract LinkedIn Profile”)
- Note the Action’s unique identifier from its URL
- 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:
- First, Create a User to represent your end-user or AI agent
- 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:
- Connect your users’ LinkedIn accounts using Username/Password Authentication
- Use our pre-configured Rented LinkedIn Accounts
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:
The response will be an array of LinkedIn profiles matching your search criteria:
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:
Each error response includes:
error_label
: A machine-readable identifier for the error typeerror_scope
: Indicates which part of the request caused the error (e.g., “input”, “auth”, “server”)error_ref
: A unique reference code for tracking and debuggingmessage
: A human-readable description of the errorstatus_code
: The HTTP status codeparams
: 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 parameters401
: Unauthorized - Invalid or missing API key403
: Forbidden - Insufficient permissions404
: Not Found - Resource doesn’t exist500
: 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.