Capturia measures its ads and site traffic with the Meta pixel and Google Analytics. You can decline at any time. Learn more

FR

Systems

1 endpoint

get/v1/systems

List Systems

Returns the account's active Systems, the main System first, then the others by name. A draft or archived System isn't listed.

A System's id is the key to pass wherever the API names one: the system_id filter of GET /v1/contacts, the system_id of a contact creation or a lead capture, the system_ids limit of a webhook. Each contact you read returns its own (system).

No cursor pagination

An account has few Systems (100 at most are returned): the list always fits on a single page. The response returns pagination.next_cursor=null and has_more=false; pagination.limit is always 100, the bound of that page, and pagination.total_count is the number of Systems returned.

Scope

contacts:read or webhooks:manage: either one is enough. A key that reads contacts reads the legend of their System here; a key that manages webhooks finds the identifiers for system_ids here. A key that has neither receives 403 insufficient_scope, which names contacts:read.

Opened account by account

Systems are opened to the API account by account. Until that is done for the key's account, the response is 403 feature_not_available (details.feature: systems): the rejection comes from the account, not the key.

Required scopes: contacts:read or webhooks:manage

Responses

StatusDescription
200

The account's active Systems.

401

The API key is missing, unknown or expired. code tells the three causes apart: missing_api_key (no Authorization: Bearer header), invalid_api_key (unknown or revoked key, or invalid format) and expired_api_key (expiration date has passed).

missing_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No API key was provided.",
    "hint": "Add an Authorization header in the form: Bearer cap_live_<your_key>",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#missing_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
invalid_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "API key is invalid or has been revoked.",
    "hint": "Verify the key in your dashboard or generate a new one.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#invalid_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
expired_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "expired_api_key",
    "message": "API key has expired.",
    "hint": "Roll the key from the dashboard to generate a new valid one.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#expired_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
403

Authorization refused. code tells apart the refusals the operation returns under this status, and each example shows one. insufficient_scope: the key has neither contacts:read nor webhooks:manage; the refusal names contacts:read. feature_not_available: details.feature names what is missing, the public API in the account's plan (public_api) or Systems, not opened to the API for this account yet (systems).

browser_not_allowed
{
  "error": {
    "type": "authorization_error",
    "code": "browser_not_allowed",
    "message": "API keys must be used from a server, never from a browser.",
    "hint": "The request carries an `Origin` header: call the API from your server, where the key stays secret.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#browser_not_allowed",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
account_suspended
{
  "error": {
    "type": "authorization_error",
    "code": "account_suspended",
    "message": "Access to this account is suspended by the Capturia team.",
    "hint": "The refusal comes from the account, not the key. While the suspension lasts, no request is accepted: contact the Capturia team.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#account_suspended",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
feature_not_availablepublic_api
{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available",
    "message": "This feature is not included in your plan.",
    "hint": "The rejection comes from the account's plan, not the key. Contact your Capturia advisor to talk it over.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#plan",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "feature": "public_api"
    }
  }
}
insufficient_scope
{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "This API key does not contain the required scope for this endpoint.",
    "hint": "This key is missing the `contacts:read` scope. Create a new key with the \"Read only\" preset or add the scope via the dashboard.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#scopes",
    "dashboard_url": "https://capturia.io/platform/dashboard/admin/integrations/api-keys/6f1e2d3c-4b5a-4c6d-8e7f-9a0b1c2d3e4f?tab=permissions",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "required_scope": "contacts:read",
      "current_scopes": [
        "leads:capture"
      ],
      "suggested_preset": "read_only"
    }
  }
}
feature_not_availablesystems
{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available",
    "message": "This feature isn't open for this account yet.",
    "hint": "Capturia opens it account by account before its launch; the rejection comes from the account, not the key. `details.feature` names it. Contact your Capturia advisor to have it opened.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#plan",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "feature": "systems"
    }
  }
}
429

Rate limit reached. rate_limit_exceeded: the key's hourly quota is used up. too_many_attempts: too many invalid keys presented from this IP address (brute-force protection). In both cases, Retry-After gives the delay in seconds.

rate_limit_exceeded
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "hint": "Retry after the number of seconds in retry_after_seconds, and consider implementing exponential backoff.",
    "doc_url": "https://capturia.io/en/developers/api/v1/rate-limits",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit": 100,
      "count": 100,
      "limit_type": "per_key",
      "retry_after_seconds": 42
    }
  }
}
too_many_attempts
{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_attempts",
    "message": "Too many invalid authentication attempts from this IP.",
    "hint": "Wait the period indicated by retry_after_seconds before trying again.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#brute-force",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit_type": "brute_force",
      "retry_after_seconds": 300
    }
  }
}
500

Unexpected server error. Always include the request_id when contacting support.

internal_error
{
  "error": {
    "type": "server_error",
    "code": "internal_error",
    "message": "Server error. The Capturia team has been notified.",
    "hint": "If this persists, contact support and include the request_id from this response.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#internal_error",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
501

Test keys (cap_test_) aren't served yet: only cap_live_ keys are accepted.

not_implemented
{
  "error": {
    "type": "server_error",
    "code": "not_implemented",
    "message": "This feature is not yet implemented.",
    "hint": "Check the API documentation for available features and the changelog for upcoming releases.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#not_implemented",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
503

A service the request depends on didn't respond (reading the key, the account or the plan). The same request will go through once it's back: retry after the Retry-After delay.

service_unavailable
{
  "error": {
    "type": "server_error",
    "code": "service_unavailable",
    "message": "Service temporarily unavailable.",
    "hint": "Retry after the period indicated by Retry-After.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#service_unavailable",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}

Example request

curl -X GET 'https://api.capturia.io/v1/systems' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'