Before diving into Captain Data’s API, it’s essential to understand the core concepts that define how our platform functions. A strong grasp of these fundamentals will help you seamlessly integrate our APIs into your application.

​
Overview of Core Entities

Relationships between core entities in Captain Data (v4) are depicted in the diagram above.

The complete Diagram is accessible here.

Key Relationships:

  • Users: Automate Actions using one or more Users.
  • Integrations: Connect to external services (e.g., LinkedIn) via Integrations.
  • Workspaces: Manage subscription details and settings in your Workspace.

​
Users

​
What is a User?

A User in Captain Data corresponds to a user in your SaaS platform or AI agent platform.

  • Users can have one or more Integrations.
  • They are essential for authentication and interacting with our APIs.

​
User Roles

  1. Owner: Full platform access. Can manage users, integrations, billing, and subscriptions.
  2. User: Limited access to the platform without billing or subscription management rights.
  3. External User: No platform access, perfect for your SaaS users. Used for linking shared integrations via API.
When creating users via API, they default to the External role.

​
Managing Users

  • User licenses are included in your plan (e.g., 5 users in the Free Trial).
  • Users can be added at no cost until you reach your plan’s license limit. Each plan includes a set number of user seats - check captaindata.com/pricing for your plan’s allocation.

As you scale, you’ll hit fair-use thresholds where we’ll limit the number of users you can sync to Captain Data. Contact [email protected] to learn more.

​
Securing Users

At Captain Data, user security is paramount. Every user is assigned a unique IP address to enhance security. Learn more about user management and security here.

​
Integrations

​
What is an Integration?

An Integration represents a connection to an external service, such as LinkedIn or HubSpot, that you can access through our APIs.

  • An Integration belongs to a single User.
  • Integrations authenticate your requests with third-party APIs and services.

​
LinkedIn Specifics

  • Captain Data applies smart limitations to prevent LinkedIn integration restrictions.
  • Supported LinkedIn licenses include Sales Navigator, Premium, and Recruiter Lite.
  • Renting LinkedIn integrations is available to help you avoid the hassle of managing or warming up connections.

Learn More:

​
Real-time API Access

​
What is the API?

Our v4 API provides direct, real-time access to data from various sources.

  • No more waiting for jobs or workflows to complete
  • Instant results through RESTful endpoints
  • Standardized error handling and response formats

​
API Features

  1. Real-time Responses:

    • Get data immediately when you make a request
    • No need to poll or wait for job completion

  2. RESTful Design:

    • Standard HTTP methods (GET, POST, etc.)
    • Clear endpoint structure
    • Consistent response formats

  3. Error Handling:

    • Standardized error responses 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": {}
}
    • Error scopes include: input, integ, param, config
    • Each error includes a unique reference ID for tracking
    • Additional parameters may be included in the params object
    • Rate limiting information is provided in headers

​
Coming Soon | Async API Mode

The async mode feature is currently in development and will be available in June 2025.

​
What is Async Mode?

Async mode provides an alternative way to process large volumes of data or long-running operations.

  • Submit requests for background processing
  • Receive a run ID to track progress
  • Use callbacks for completion notifications
  • Ideal for batch operations or when real-time responses aren’t required

​
When to Use Async Mode

  1. Large Data Sets:

    • Processing thousands of records
    • Complex data transformations
    • Bulk operations

  2. Long-running Operations:

    • Operations that take more than 30 seconds
    • Resource-intensive tasks
    • Rate-limited operations

  3. Background Processing:

    • Non-critical operations
    • Scheduled tasks
    • Batch processing

While async mode provides more flexibility for large-scale operations, real-time mode is recommended for most use cases due to its simplicity and immediate results.