Skip to main content
POST
/
v2
/
events
curl --request POST \
  --url https://pub-api.conversion.ai/api/v2/events \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "email": "jane@example.com",
  "event": "log_in",
  "data": {
    "device": "mobile",
    "location": "US"
  }
}
'
{
  "data": {
    "cnvEventId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Authorizations

​
X-API-Key
string
header
required

Your Conversion API key. Found in Settings > Integrations in the dashboard. Format: sk_live_<key_id>_<secret>.

Body

application/json
​
event
string
required

The name of the custom event to track (e.g. order_completed, log_in). This is a freeform string.

Example:

"page_viewed"

​
userId
string

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.

Example:

"user_12345"

​
email
string<email>

The contact's email address. At least one of userId or email is required.

Example:

"jane@example.com"

​
eventId
string

An optional client-generated identifier for the event. Use stable identifiers (like order IDs) to enable idempotent updates. If an event with this ID already exists, its data is updated in place. If omitted, a new event is always created.

Example:

"evt_abc123"

​
data
object

An optional map of custom data to attach to the event.

Example:
{ "product_id": "1234567890", "quantity": 2 }
​
timestamp
string<date-time>

An optional ISO 8601 timestamp for when the event occurred. Defaults to the current time if omitted.

Example:

"2026-03-31T14:30:00Z"

Response

Event tracked successfully.

​
data
object