> For the complete documentation index, see [llms.txt](https://developer.parvenu.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.parvenu.io/getting-started/response-format.md).

# 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`.

```json
{
  "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`.             |

{% hint style="info" %}
The finished status is `done`. Poll [Check List Status](/get-enrichment-results/check-list-status.md) until you see it, then download the list.
{% endhint %}

## Errors

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

```json
{
  "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.