Conversion Events API

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.'