COconversion

Track Event

Record a custom event for a contact.

post/v2/events

Request

  • Base URL
    https://pub-api.conversion.ai/api
  • Auth
    • API key in header X-API-Key
    • or API key in query parameter api_key

Request body

userIdstring

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.

emailstring email

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

eventstring required

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

eventIdstring

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.

dataobject

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

timestampstring date-time

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

createContactboolean

When true, creates the contact if no existing contact matches userId or email. Creating a contact requires an email.

Example request

{
  "userId": "user_12345",
  "email": "jane@example.com",
  "event": "page_viewed",
  "eventId": "evt_abc123",
  "data": {
    "product_id": "1234567890",
    "quantity": 2
  },
  "timestamp": "2026-03-31T14:30:00Z",
  "createContact": true
}

Response

Event tracked successfully.

Changes

No recorded changes to this operation across all 1 revision of this API.