Skip to main content
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" }'

​
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
  }
}

​
HTTP status codes

StatusMeaning
200Request succeeded.
400The request was malformed or contained invalid data. Check the error.code and error.message fields for details.
401Authentication failed. The API key is missing or invalid.
404The requested resource was not found (e.g., contact not found when updateOnly is true).
500An 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.
CodeDescription
missing_identifierNeither email nor cnvContactId was provided. At least one is required.
invalid_emailThe provided email address is malformed.
invalid_subscription_statusThe subscription status value is not one of the allowed values (SUBSCRIBED, UNSUBSCRIBED, NO_STATUS).
invalid_fieldA field key in fields or companyFields does not exist or refers to a read-only field.
contact_not_foundNo existing contact matched the provided identifier. Returned when updateOnly is true.
upsert_failedThe upsert operation failed for a contact in a batch request.
internal_errorAn unexpected server-side failure. Retry with exponential backoff.

​
Pagination

The current API endpoints do not use pagination. Batch endpoints accept up to 1,000 contacts per request.