API Overview

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.

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.

{
  "data": {
    "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "contactCreated": true
  }
}

{
  "error": {
    "code": "invalid_email",
    "message": "invalid email format: not-an-email"
  }
}

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.

{
  "data": {
    "fields": [ ... ]
  },
  "pagination": {
    "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwWiJ9"
  }
}

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

Getting Started

Contacts

Events

Workflows

Fields

Forms

Audiences

Campaigns

Exports

Zapier

Base URL

Request format

Rate limits

Response envelope

HTTP status codes

Error codes

​Base URL

​Request format

​Rate limits

​Response envelope

​HTTP status codes

​Error codes

​Pagination

Base URL

Request format

Rate limits

Response envelope

HTTP status codes

Error codes

Pagination