Overview
API reference
Common response structure, shared types, and error codes for all endpoints.
Every endpoint returns a consistent JSON structure. This page documents the shared envelope, types, and error codes that apply across all endpoints.
Response envelope
Every response uses a consistent JSON envelope with five top-level fields:
Response
| Field | Type | Description |
|---|---|---|
success | boolean | true if the request was processed successfully |
data | object | null | The endpoint-specific result payload (null on error or when no data is returned) |
errorobjectShow child attributesHide child attributes
| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error code (e.g. API_KEY_MISSING, API_KEY_MALFORMED, VALIDATION_ERROR, PAGINATION_LIMIT_EXCEEDED) |
message | string | Human-readable error description |
details | object | Additional context (only present on some errors) |
null when success is true.
quotasobjectShow child attributesHide child attributes
| Field | Type | Description |
|---|---|---|
creditsConsumed | number | Credits used for this request after pricing resolution |
workspaceobjectShow child attributesHide child attributes
| Field | Type | Description |
|---|---|---|
id | string | Your workspace identifier |
hasUnlimitedCredits | boolean | Whether workspace credits are unlimited |
allowDailyOvercost | boolean | Whether the workspace may exceed its daily cap (Enterprise only) |
creditsobjectShow child attributesHide child attributes
| Field | Type | Description |
|---|---|---|
total | number | Total credits in your plan |
used | number | Credits consumed so far |
left | number | Remaining credits |
dailyLimitobjectShow child attributesHide child attributes
| Field | Type | Description |
|---|---|---|
limit | number | Maximum requests per day |
used | number | Requests made today |
left | number | Remaining requests today |
nextReset | string | null | When the daily window resets (ISO 8601) |
null when no daily limit is configured.
minuteRateLimitobjectShow child attributesHide child attributes
| Field | Type | Description |
|---|---|---|
limit | number | Maximum requests per minute |
used | number | Requests made in the current minute |
left | number | Remaining requests in the current minute |
nextReset | string | null | When the minute window resets (ISO 8601) |
keyobjectShow child attributesHide child attributes
| Field | Type | Description |
|---|---|---|
id | string | API key identifier |
dailyLimitobjectShow child attributesHide child attributes
| Field | Type | Description |
|---|---|---|
limit | number | Maximum requests per day |
used | number | Requests made today |
left | number | Remaining requests today |
nextReset | string | null | When the daily window resets (ISO 8601) |
null when no daily limit is configured.
minuteRateLimitobjectShow child attributesHide child attributes
| Field | Type | Description |
|---|---|---|
limit | number | Maximum requests per minute |
used | number | Requests made in the current minute |
left | number | Remaining requests in the current minute |
nextReset | string | null | When the minute window resets (ISO 8601) |
The key field is null when the request is made from the dashboard (no API key).
When authentication or quota context is unavailable (e.g. invalid API key), quotas may be omitted.
metadataobjectShow child attributesHide child attributes
| Field | Type | Description |
|---|---|---|
requestId | string | Unique identifier for this request (useful for support inquiries) |
executionTimeMs | number | Total execution time in milliseconds |
updatedAt | string | Last upstream update timestamp (ISO 8601). Present only when available. |
Shared types
Some types are reused across multiple endpoints. They are documented here once to avoid repetition -- individual endpoint pages reference them by name.
DateRange
| Field | Type | Description |
|---|---|---|
start | string | null | Start date (ISO 8601) |
end | string | null | End date (ISO 8601, null if current) |
Error codes
| Status | Description |
|---|---|
400 | Invalid JSON body |
401 | Missing, malformed, invalid, or expired API key |
402 | No credits left, purchase more to continue. The free /check endpoints return NO_CREDITS |
403 | Workspace disabled (WORKSPACE_DISABLED) or API key lacks permission |
404 | Data not found |
422 | V2 schema/validation error, INVALID_LINKEDIN_URL, disposable email domain, or missing webhook URL on async endpoints |
422 | PAGINATION_LIMIT_EXCEEDED on search endpoints when company-search page exceeds 50, or perPage exceeds 100 on people or company search. Details: { "field": "page", "max": 50 } or { "field": "perPage", "max": 100 } |
429 | Rate limit exceeded , wait and retry after nextReset |
451 | Data Subject Blocked , the profile has been removed per GDPR/CCPA data subject request |
5xx | Temporary upstream or platform issue , retry with backoff |
WORKSPACE_DISABLED is 403 for both dashboard and API-key authentication. INVALID_LINKEDIN_URL and VALIDATION_ERROR return 422.