Response Format

Every endpoint returns the same envelope. Read this once and every other page in these docs reads the same way.

Every successful call returns the same outer shape. The part that changes from endpoint to endpoint is what sits inside data.

{
  "status": "success",
  "data": { },
  "credits_used": 1,
  "credits_remaining": 4823,
  "success": true
}

Field	Type	Description
status	string	Lowercase. See the two tables below.
data	object or array	The result. An object for a single record, an array when the endpoint returns many.
credits_used	number	Credits this call cost. 0 on free endpoints and when nothing was found.
credits_remaining	number	Your balance after the call.
total	number	Row count. Present when data is an array.
message	string	Plain-English note. Present when there is something to say, such as a lookup that is still running.
success	boolean	true unless status is error. Kept for older clients — prefer status.

Status values

Endpoints that answer immediately use:

Status	Meaning
success	A record was found and is in data.
not_found	The call worked, but there is no record for that input. Usually free.
error	The call failed. See error.

Endpoints that start a background job — anything ending in _list, plus the lookups that can run long — use:

Status	Meaning
queued	Accepted, not started yet.
processing	Running. Call again shortly.
done	Finished. Download the results.
not_found	Finished with nothing to return.
cancelled	Stopped before it finished.
error	Failed. See error.

The finished status is done. Poll Check List Status until you see it, then download the list.

Errors

Failures return the same envelope with an error object and no data.

{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "api_key: Field required"
  },
  "success": false
}

Code	When
validation_error	The request body is missing a field or has the wrong type.
not_found	The path or the record does not exist.
http_error	Anything else the API rejected.

Extra fields

Rich records — people, companies, jobs — keep the named fields at the top of data, in the same place on every endpoint that returns them. Anything the source supplied that has no named field is kept under extra on the same record, so nothing is dropped. Treat extra as informational: its contents vary by source and are not guaranteed to stay the same.