> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Learn how the Conversion API works, including base URLs, response formats, and error handling.

The Conversion API lets you programmatically manage contacts and their associated data. All endpoints use JSON request and response bodies over HTTPS.

## Base URL

All API requests are made to the following base URL:

```
https://pub-api.conversion.ai/api
```

## Request format

All requests must include the `Content-Type: application/json` header and send a JSON request body.

```bash theme={null}
curl -X POST https://pub-api.conversion.ai/api/v2/contacts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{ "email": "jane@example.com" }'
```

## Rate limits

All API endpoints share a rate limit of **200 requests per second**. For high-volume writes, use the batch endpoints.

## Response envelope

Every response uses a consistent JSON envelope. Successful responses return a `data` object. Failed responses return an `error` object.

<CodeGroup>
  ```json Success (200) theme={null}
  {
    "data": {
      "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "contactCreated": true
    }
  }
  ```

  ```json Error (4xx / 5xx) theme={null}
  {
    "error": {
      "code": "invalid_email",
      "message": "invalid email format: not-an-email"
    }
  }
  ```
</CodeGroup>

## HTTP status codes

| Status | Meaning                                                                                                             |
| ------ | ------------------------------------------------------------------------------------------------------------------- |
| `200`  | Request succeeded.                                                                                                  |
| `400`  | The request was malformed or contained invalid data. Check the `error.code` and `error.message` fields for details. |
| `401`  | Authentication failed. The API key is missing or invalid.                                                           |
| `403`  | The API key is valid, but the endpoint is not enabled for this account. See the `export_not_enabled` error code.    |
| `404`  | The requested resource was not found (e.g., contact not found when `updateOnly` is true).                           |
| `500`  | An unexpected server error occurred. Retry with exponential backoff.                                                |

## Error codes

When a request fails, the `error.code` field contains a machine-readable error code. Use these codes for programmatic error handling.

| Code                          | Description                                                                                                            |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `missing_identifier`          | Neither `email` nor `cnvContactId` was provided. At least one is required.                                             |
| `invalid_email`               | The provided email address is malformed.                                                                               |
| `invalid_subscription_status` | The subscription status value is not one of the allowed values (`SUBSCRIBED`, `UNSUBSCRIBED`, `NO_STATUS`).            |
| `invalid_field`               | A field key in `fields` or `companyFields` does not exist or refers to a read-only field.                              |
| `contact_not_found`           | No existing contact matched the provided identifier. Returned when `updateOnly` is true.                               |
| `upsert_failed`               | The upsert operation failed for a contact in a batch request.                                                          |
| `invalid_object_type`         | The object type is not one of the supported values (`CONTACT`, `COMPANY`, `OPPORTUNITY`, `CAMPAIGN_MEMBER`).           |
| `invalid_cursor`              | The pagination cursor is invalid or malformed. Use the `nextCursor` value returned by a previous response.             |
| `export_not_enabled`          | The endpoint is not enabled for this account. Contact the Conversion team to request access. Returned with HTTP `403`. |
| `internal_error`              | An unexpected server-side failure. Retry with exponential backoff.                                                     |

## Pagination

List endpoints (such as List Fields) use opaque cursor-based pagination. The page size is controlled by the `limit` query parameter; each endpoint documents its default and maximum, and values are clamped to the allowed range rather than rejected.

Paginated responses include a `pagination` object alongside `data`. Its `nextCursor` field holds the token for the next page, or `null` when there are no more results — this is the single source of truth for whether more results exist (there is no separate `hasMore` flag). Pass the returned value back as the `cursor` query parameter to fetch the next page. Treat the cursor as a black box; an invalid or malformed cursor returns an `invalid_cursor` error.

```json theme={null}
{
  "data": {
    "fields": [ ... ]
  },
  "pagination": {
    "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwWiJ9"
  }
}
```

```bash theme={null}
# First page
curl "https://pub-api.conversion.ai/api/v2/fields?objectType=CONTACT&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

# Next page, using nextCursor from the previous response
curl "https://pub-api.conversion.ai/api/v2/fields?objectType=CONTACT&limit=50&cursor=eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwWiJ9" \
  -H "X-API-Key: YOUR_API_KEY"
```

Batch (write) endpoints do not use pagination and accept up to 1,000 contacts per request.