---
title: "Track Event"
method: POST
path: "/v2/events"
---

# Track Event

`POST /v2/events`

## Request

- Base URL: `https://pub-api.conversion.ai/api`
- URL: `https://pub-api.conversion.ai/api/v2/events`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`

Record a custom event for a contact.

## Request body

- object
  - `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.
  - `email` string, email: The contact's email address. At least one of `userId` or `email` is required.
  - `event` string, required: The name of the custom event to track (e.g. `order_completed`, `log_in`). This is a freeform string.
  - `eventId` string: 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.
  - `data` object: An optional map of custom data to attach to the event.
  - `timestamp` string, date-time: An optional ISO 8601 timestamp for when the event occurred. Defaults to the current time if omitted.
  - `createContact` boolean: When `true`, creates the contact if no existing contact matches `userId` or `email`. Creating a contact requires an `email`.

## Response `200`

Event tracked successfully.

- object
  - `data` object
    - `cnvEventId` string, uuid: The Conversion engagement ID for the recorded event. For a duplicate, this is the ID of the originally recorded event.
    - `cnvContactId` string, uuid: The Conversion contact ID of the contact the event was recorded against. Omitted for duplicates.
    - `duplicate` boolean: `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`.

## Other responses

- `400`: The request was malformed or contained invalid data.
- `401`: Authentication failed.
- `404`: The contact could not be found.
- `409`: The provided identifiers conflict with an existing contact.
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/conversion/apis/conversion-api.md) - [All operations](https://skmtc.dev/conversion/apis/conversion-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conversion/apis/conversion-api/revisions/8422f815402a?raw)