Conversion Events API
The Events API from Conversion — 2 operation(s) for events.
The Events API from Conversion — 2 operation(s) for events.
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-events-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 Events 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: Events
paths:
/v2/events:
post:
operationId: trackEvent
summary: Track Event
description: Record a custom event for a contact.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- event
properties:
userId:
type: string
description: An external user identifier for the contact. At least one of `userId` or `email` is required. If `userId` matches a contact, that contact is used. If not, falls back to `email`. If the email matches a contact that has a different `userId`, a `conflicting_identifier` error is returned.
examples:
- user_12345
email:
type: string
format: email
description: The contact's email address. At least one of `userId` or `email` is required.
examples:
- jane@example.com
event:
type: string
description: The name of the custom event to track (e.g. `order_completed`, `log_in`). This is a freeform string.
examples:
- page_viewed
eventId:
type: string
description: 'An optional client-generated identifier for the event. Use stable identifiers (like order IDs) to make retries idempotent: if an event with this ID already exists, the duplicate is ignored, the existing event is left unchanged, and the response reports success with `duplicate: true` and the original event''s `cnvEventId`. If omitted, a new event is always created.'
examples:
- evt_abc123
data:
type: object
additionalProperties: {}
description: An optional map of custom data to attach to the event.
examples:
- product_id: '1234567890'
quantity: 2
timestamp:
type: string
format: date-time
description: An optional ISO 8601 timestamp for when the event occurred. Defaults to the current time if omitted.
examples:
- '2026-03-31T14:30:00Z'
createContact:
type: boolean
default: false
description: When `true`, creates the contact if no existing contact matches `userId` or `email`. Creating a contact requires an `email`.
examples:
- true
examples:
track-with-email:
summary: Track event by email
value:
email: jane@example.com
event: log_in
data:
device: mobile
location: US
track-with-userId:
summary: Track event by userId
value:
userId: user_12345
event: plan_upgraded
data:
plan: pro
annual: true
track-with-idempotency:
summary: Track event with idempotency key
value:
email: jane@example.com
event: order_completed
eventId: evt_abc123
data:
product_id: '1234567890'
quantity: 2
timestamp: '2026-03-31T14:30:00Z'
track-and-create-contact:
summary: Track event and create the contact if missing
value:
userId: user_67890
email: new-user@example.com
event: signed_up
createContact: true
responses:
'200':
description: Event tracked successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
cnvEventId:
type: string
format: uuid
description: The Conversion engagement ID for the recorded event. For a duplicate, this is the ID of the originally recorded event.
cnvContactId:
type: string
format: uuid
description: The Conversion contact ID of the contact the event was recorded against. Omitted for duplicates.
duplicate:
type: boolean
description: '`true` when an event with the same `eventId` was already tracked. The request is an idempotent no-op: the existing event is unchanged and no new event is created. Omitted when `false`.'
examples:
tracked:
summary: Event tracked
value:
data:
cnvEventId: b2c3d4e5-f6a7-8901-bcde-f12345678901
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
duplicate:
summary: Duplicate event (already tracked)
value:
data:
cnvEventId: b2c3d4e5-f6a7-8901-bcde-f12345678901
duplicate: true
'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 'userId' or 'email' is required
missing-event:
summary: Missing event name
value:
error:
code: missing_event
message: '''event name'' is required'
invalid-email:
summary: Invalid email
value:
error:
code: invalid_email
message: 'invalid email format: not-an-email'
missing-email:
summary: createContact without an email for a new contact
value:
error:
code: missing_email
message: '''email'' is required to create a contact that does not exist'
'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: The contact could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
contact-not-found:
summary: Contact not found
value:
error:
code: contact_not_found
message: contact not found
contact-id-not-found:
summary: Contact ID not found
value:
error:
code: contact_id_not_found
message: contact not found with the provided contactId
'409':
description: The provided identifiers conflict with an existing contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
conflicting-identifier:
summary: Conflicting identifier
value:
error:
code: conflicting_identifier
message: contact found by email but has a different userId
'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 track event
tags:
- Events
/v2/events/batch:
post:
operationId: batchTrackEvents
summary: Batch Track Events
description: 'Record up to 200 custom events in a single request. Each event is processed independently.
The response includes summary counts and a per-event error list for any failures. Partial failures do not cause the entire request to fail.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- events
properties:
events:
type: array
minItems: 1
maxItems: 200
description: An array of event objects to track.
items:
type: object
description: A single event to track.
required:
- event
properties:
userId:
type: string
description: An external user identifier for the contact. At least one of `userId` or `email` is required. If `userId` matches a contact, that contact is used. If not, falls back to `email`. If the email matches a contact that has a different `userId`, a `conflicting_identifier` error is returned.
examples:
- user_12345
email:
type: string
format: email
description: The contact's email address. At least one of `userId` or `email` is required.
examples:
- jane@example.com
event:
type: string
description: The name of the custom event to track. This is a freeform string.
examples:
- log_in
eventId:
type: string
description: 'An optional client-generated identifier for the event. Use stable identifiers (like order IDs) to make retries idempotent: if an event with this ID already exists, the duplicate is ignored, the existing event is left unchanged, and the response reports success with `duplicate: true` and the original event''s `cnvEventId`. If omitted, a new event is always created.'
examples:
- evt_abc123
data:
type: object
additionalProperties: {}
description: An optional map of custom data to attach to the event.
timestamp:
type: string
format: date-time
description: An optional ISO 8601 timestamp for when the event occurred. Defaults to the current time if omitted.
createContact:
type: boolean
default: false
description: When `true`, creates the contact for this event if no existing contact matches `userId` or `email`. Overrides a `false` top-level `createContacts`. Creating a contact requires an `email`.
createContacts:
type: boolean
default: false
description: When `true`, creates the contact for every event in the batch whose `userId` or `email` matches no existing contact. Creating a contact requires an `email`.
examples:
- true
examples:
basic:
summary: Basic batch track
value:
events:
- email: jane@example.com
event: log_in
data:
device: mobile
location: US
timestamp: '2026-03-31T14:30:00Z'
- userId: user_12345
event: plan_upgraded
data:
plan: pro
timestamp: '2026-03-31T14:30:00Z'
create-missing-contacts:
summary: Batch track and create missing contacts
value:
createContacts: true
events:
- email: new-user@example.com
userId: user_67890
event: signed_up
- email: jane@example.com
event: log_in
responses:
'200':
description: Batch processed. Check `errors` for individual failures.
content:
application/json:
schema:
type: object
properties:
data:
type: object
required:
- processed
- tracked
- failed
- results
properties:
processed:
type: integer
description: Total number of events in the request.
tracked:
type: integer
description: Number of events successfully tracked, including idempotent duplicates of already-tracked events.
failed:
type: integer
description: Number of events that failed.
results:
type: array
description: An array of result objects in the same order as the input `events` array.
items:
type: object
required:
- success
properties:
success:
type: boolean
description: '`true` if the event was successfully tracked (including idempotent duplicates).'
cnvEventId:
type: string
format: uuid
description: The Conversion engagement ID. Present on success. For a duplicate, this is the ID of the originally recorded event.
cnvContactId:
type: string
format: uuid
description: The Conversion contact ID. Present on success, but omitted for duplicates.
duplicate:
type: boolean
description: '`true` when an event with the same `eventId` was already tracked. The row is an idempotent no-op: the existing event is unchanged and no new event is created. Omitted when `false`.'
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 events tracked
value:
data:
processed: 2
tracked: 2
failed: 0
results:
- success: true
cnvEventId: b2c3d4e5-f6a7-8901-bcde-f12345678901
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
- success: true
cnvEventId: c3d4e5f6-a7b8-9012-cdef-123456789012
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
partial-failure:
summary: Partial failure
value:
data:
processed: 4
tracked: 2
failed: 2
results:
- success: false
error: invalid_email
message: 'invalid email format: not-an-email'
- success: true
cnvEventId: b2c3d4e5-f6a7-8901-bcde-f12345678901
cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
- success: false
error: contact_not_found
message: contact not found
- success: true
cnvEventId: d4e5f6a7-b8c9-0123-def1-234567890123
duplicate: true
'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 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 track events
tags:
- Events
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'
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.'