Conversion Contacts API
The Contacts API from Conversion — 2 operation(s) for contacts.
The Contacts API from Conversion — 2 operation(s) for contacts.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/conversion:conversion-contacts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Conversion Contacts API
version: 2.0.0
description: The Conversion API lets you programmatically manage contacts, track custom events, and manage their associated data.
servers:
- url: https://pub-api.conversion.ai/api
security:
- apiKey: []
- apiKeyQuery: []
tags:
- name: Contacts
paths:
/v2/contacts:
post:
operationId: upsertContact
summary: Upsert Contact
description: Create a new contact or update an existing one. Contacts are identified by `email` or `cnvContactId`. If the contact exists, its fields are updated; if not, a new contact is created.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
description: The contact's email address. At least one of `email` or `cnvContactId` is required. When both are provided, `cnvContactId` identifies the contact and `email` updates the contact's email address.
examples:
- jane@example.com
cnvContactId:
type: string
format: uuid
description: The Conversion contact ID. Use this to identify an existing contact by its internal ID instead of email. At least one of `email` or `cnvContactId` is required.
examples:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
subscriptionStatus:
$ref: '#/components/schemas/SubscriptionStatus'
fields:
$ref: '#/components/schemas/ContactFields'
companyFields:
$ref: '#/components/schemas/CompanyFields'
updateOnly:
type: boolean
default: false
description: When `true`, restricts the operation to updates only. Returns a `contact_not_found` error if no existing contact matches the provided identifier.
syncToCRM:
type: boolean
default: false
description: When `true`, syncs the contact to the connected CRM (e.g., Salesforce) if the contact does not already have an external CRM record.
preserveExistingFields:
type: boolean
default: false
description: When `true`, prevents overwriting existing non-empty field values. New values are only written to fields that are currently empty or unset. Useful for enrichment workflows.
examples:
create-with-fields:
summary: Create contact with fields
value:
email: jane@example.com
subscriptionStatus: SUBSCRIBED
fields:
first_name: Jane
last_name: Smith
job_title: VP of Marketing
companyFields:
company_name: Acme Corp
update-by-id:
summary: Update by contact ID
value:
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
fields:
job_title: Director of Marketing
enrich:
summary: Enrich without overwriting
value:
email: jane@example.com
preserveExistingFields: true
fields:
first_name: Jane
last_name: Smith
phone: +1-555-0100
responses:
'200':
description: Contact upserted successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
required:
- cnvContactId
- contactCreated
properties:
cnvContactId:
type: string
format: uuid
description: The Conversion contact ID of the created or updated contact.
contactCreated:
type: boolean
description: '`true` if a new contact was created, `false` if an existing contact was updated.'
examples:
created:
summary: Contact created
value:
data:
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
contactCreated: true
updated:
summary: Contact updated
value:
data:
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
contactCreated: false
'400':
description: The request was malformed or contained invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing-identifier:
summary: Missing identifier
value:
error:
code: missing_identifier
message: either 'email' or 'cnvContactId' is required
invalid-email:
summary: Invalid email
value:
error:
code: invalid_email
message: 'invalid email format: not-an-email'
invalid-field:
summary: Unknown field
value:
error:
code: invalid_field
message: field 'nonexistent_key' does not exist
invalid-subscription-status:
summary: Invalid subscription status
value:
error:
code: invalid_subscription_status
message: invalid subscription status value
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unauthorized:
summary: Missing or invalid API key
value:
error:
code: unauthorized
message: API key is required
'404':
description: Contact not found (when `updateOnly` is true).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
not-found:
summary: Contact not found
value:
error:
code: contact_not_found
message: no contact found with the provided identifier
'500':
description: An unexpected server error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
internal:
summary: Internal error
value:
error:
code: internal_error
message: failed to upsert contact
tags:
- Contacts
get:
operationId: getContact
summary: Get Contact
description: 'Fetch a single contact by `email` or `cnvContactId`. Provide exactly one identifier; `cnvContactId` takes precedence when both are provided.
When looking up by `email`, the most recently updated contact with that email address is returned.
> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.'
parameters:
- name: email
in: query
required: false
schema:
type: string
format: email
description: The contact's email address. When multiple contacts share the same email, the most recently updated contact is returned.
examples:
example:
value: jane@example.com
- name: cnvContactId
in: query
required: false
schema:
type: string
format: uuid
description: The Conversion contact ID.
examples:
example:
value: a1b2c3d4-e5f6-7890-abcd-ef1234567890
responses:
'200':
description: Contact retrieved successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
required:
- contact
properties:
contact:
$ref: '#/components/schemas/Contact'
examples:
found:
summary: Contact found
value:
data:
contact:
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
email: jane@example.com
userId: user_12345
subscriptionStatus: SUBSCRIBED
fields:
first_name: Jane
last_name: Smith
job_title: VP of Marketing
createdAt: '2026-01-10T08:00:00Z'
updatedAt: '2026-02-03T14:22:05Z'
'400':
description: The request was malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing-identifier:
summary: Missing identifier
value:
error:
code: missing_identifier
message: at least one of email or cnvContactId is required
invalid-email:
summary: Invalid email
value:
error:
code: invalid_email
message: 'invalid email format: not-an-email'
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unauthorized:
summary: Missing or invalid API key
value:
error:
code: unauthorized
message: API key is required
'403':
description: This endpoint is not enabled for this account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
not-enabled:
summary: Endpoint not enabled
value:
error:
code: export_not_enabled
message: business is not authorized to use this endpoint
'404':
description: The contact was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
contact-not-found:
summary: Contact not found
value:
error:
code: contact_not_found
message: no contact found matching the provided identifier
'500':
description: An unexpected server error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
internal:
summary: Internal error
value:
error:
code: internal_error
message: failed to get contact
tags:
- Contacts
/v2/contacts/batch:
post:
operationId: batchUpsertContacts
summary: Batch Upsert Contacts
description: Create or update up to 1,000 contacts in a single request, with a result for each contact. Optionally pass `audienceId` to add successfully upserted contacts to a static audience.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- contacts
properties:
contacts:
type: array
minItems: 1
maxItems: 1000
description: An array of contact objects to upsert.
items:
type: object
description: A single contact to upsert. Provide at least one of `email`, `cnvContactId`, or `userId`. Matching prioritizes `cnvContactId`, then `userId`, then email.
properties:
email:
type: string
format: email
description: The contact's email address. Required when creating a new contact; updates the email when matching an existing contact by ID.
examples:
- jane@example.com
cnvContactId:
type: string
format: uuid
description: The Conversion contact ID. Takes precedence over `userId` and email when identifying an existing contact.
examples:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
userId:
type: string
description: Your stable contact identifier, scoped to your workspace. If unmatched, email can match a contact with no user ID and assign this ID; a different existing user ID creates a separate contact unless `updateOnly` is true. Blank values are ignored and do not clear the ID.
examples:
- user_12345
subscriptionStatus:
$ref: '#/components/schemas/SubscriptionStatus'
fields:
$ref: '#/components/schemas/ContactFields'
companyFields:
$ref: '#/components/schemas/CompanyFields'
updateOnly:
type: boolean
default: false
description: When `true`, restricts all operations to updates only. Contacts that are not found will be returned with a `contact_not_found` error in their result item.
syncToCRM:
type: boolean
default: false
description: When `true`, syncs upserted contacts to the connected CRM (e.g., Salesforce) if they do not already have an external CRM record.
preserveExistingFields:
type: boolean
default: false
description: When `true`, prevents overwriting existing non-empty field values for all contacts in the batch. New values are only written to fields that are currently empty or unset.
audienceId:
type: string
format: uuid
description: Optional Conversion static audience ID. Add successfully upserted contacts to this audience. The audience must belong to the API key workspace.
examples:
basic:
summary: Basic batch upsert
value:
contacts:
- email: jane@example.com
subscriptionStatus: SUBSCRIBED
fields:
first_name: Jane
last_name: Smith
- email: bob@example.com
subscriptionStatus: SUBSCRIBED
fields:
first_name: Bob
last_name: Jones
companyFields:
company_name: Acme Corp
enrichment:
summary: Enrichment mode
value:
preserveExistingFields: true
contacts:
- email: jane@example.com
fields:
first_name: Jane
phone: +1-555-0100
audience:
summary: Upsert contacts and add audience membership
value:
audienceId: 8e112222-3333-4444-8555-666677778888
contacts:
- email: jane@example.com
fields:
first_name: Jane
responses:
'200':
description: Batch processed. Check data.failed and each result for contact or audience failures. An invalid audience is reported for each contact before any writes.
content:
application/json:
schema:
type: object
properties:
data:
type: object
required:
- processed
- succeeded
- failed
- results
properties:
processed:
type: integer
description: The total number of contacts in the batch.
succeeded:
type: integer
description: The number of contacts with all requested operations completed.
failed:
type: integer
description: The number of contacts that failed.
results:
type: array
description: An array of result objects in the same order as the input `contacts` array.
items:
type: object
required:
- success
properties:
success:
type: boolean
description: True if the contact was upserted and, when audienceId is supplied, added to that audience.
cnvContactId:
type: string
format: uuid
description: The saved contact ID, including when the audience add fails.
contactCreated:
type: boolean
description: True if a new contact was created. Retained if the audience add fails.
error:
type: string
description: A machine-readable error code. Present on failure.
message:
type: string
description: A human-readable error description. Present on failure.
examples:
all-success:
summary: All contacts upserted
value:
data:
processed: 2
succeeded: 2
failed: 0
results:
- success: true
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
contactCreated: true
- success: true
cnvContactId: f9e8d7c6-b5a4-3210-fedc-ba9876543210
contactCreated: false
partial-failure:
summary: Partial failure
value:
data:
processed: 2
succeeded: 1
failed: 1
results:
- success: true
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
contactCreated: true
- success: false
error: invalid_email
message: 'invalid email format: not-an-email'
audience-add-failure:
summary: Contact saved but audience add failed
value:
data:
processed: 1
succeeded: 0
failed: 1
results:
- success: false
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
contactCreated: true
error: audience_add_failed
message: contact saved, but audience membership could not be confirmed
'400':
description: Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-request:
summary: Invalid request body
value:
error:
code: invalid_request
message: request validation failed
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unauthorized:
summary: Missing or invalid API key
value:
error:
code: unauthorized
message: API key is required
'500':
description: An internal error prevented batch processing.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
internal:
summary: Internal error
value:
error:
code: internal_error
message: failed to upsert contacts
'403':
description: The API key lacks contact write permissions or edit access to the audience.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Contacts
components:
schemas:
Error:
type: object
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: A machine-readable error code.
examples:
- invalid_email
message:
type: string
description: A human-readable error description.
examples:
- 'invalid email format: not-an-email'
Contact:
type: object
required:
- cnvContactId
- fields
- createdAt
- updatedAt
properties:
cnvContactId:
type: string
format: uuid
description: The Conversion contact ID.
email:
type:
- string
- 'null'
format: email
description: The contact's email address, or `null` when not set.
userId:
type:
- string
- 'null'
description: An external user identifier for the contact, or `null` when not set.
subscriptionStatus:
$ref: '#/components/schemas/SubscriptionStatus'
fields:
$ref: '#/components/schemas/ContactFields'
createdAt:
type: string
format: date-time
description: When the contact was created.
updatedAt:
type: string
format: date-time
description: When the contact was last updated.
CompanyFields:
type: object
additionalProperties: {}
description: A map of company field keys to values for the contact's associated company.
examples:
- company_name: Acme Corp
industry: Technology
ContactFields:
type: object
additionalProperties: {}
description: A map of contact field keys to values. Keys must match existing field definitions in your Conversion account.
examples:
- first_name: Jane
last_name: Smith
job_title: VP of Marketing
SubscriptionStatus:
type: string
enum:
- SUBSCRIBED
- UNSUBSCRIBED
- NO_STATUS
description: The contact's email subscription status. System-managed statuses (`BOUNCED`, `COMPLAINED`, etc.) cannot be set through the API.
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-API-Key
description: 'Your Conversion API key. Found in **Settings > Integrations** in the dashboard. Format: `sk_live_<key_id>_<secret>`.'
apiKeyQuery:
type: apiKey
in: query
name: api_key
description: 'Your Conversion API key, sent as a query parameter instead of the `X-API-Key` header. Prefer the header: URLs can end up in logs and browser history.'