API reference

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

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

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.

Tip

Include metadata.requestId from error responses when contacting support – it speeds up troubleshooting.

quotasobjectShow child attributesHide child attributes

creditsConsumed number

Credits used for this request after pricing resolution

workspaceobjectShow child attributesHide child attributes

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

total number

Total credits in your plan

used number

Credits consumed so far

left number

Remaining credits

dailyLimitobjectShow child attributesHide child attributes

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

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

id string

API key identifier

dailyLimitobjectShow child attributesHide child attributes

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

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

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

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 or legacy V1/RC endpoint validation (`VALIDATION_ERROR`)
`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

Tip

For 429 errors, read the quotas.workspace.minuteRateLimit.nextReset field and retry after that timestamp.

Tip

For 5xx errors, use exponential backoff starting at 1 second.

WORKSPACE_DISABLED is 403 for both dashboard and API-key authentication. INVALID_LINKEDIN_URL is 422 on both V1 and V2. VALIDATION_ERROR remains route-sensitive: legacy V1/RC routes return 400, while V2 routes return 422.

Note

For async endpoints, the initial response is a standard V2 acknowledgement containing a webhookId. Most async endpoints support polling or a webhook callback; the Contact Email Finder uses the webhook flow and delivers an email array or an error code in its callback. Webhook callback payloads do not use the full V2 envelope.