---
title: "Submit a conversion event"
method: POST
path: "/events"
tags: ["Event"]
---

# Submit a conversion event

`POST /events`

## Request

- Base URL: `https://plainrouter.com/api/v1`
- URL: `https://plainrouter.com/api/v1/events`
- Auth: HTTP bearer

Accepts a consent-aware server-side conversion event and uses event_id or Idempotency-Key to make retries idempotent.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `event_id` string: Caller-supplied idempotency key; maximum 128 characters.
    - `event_name` string, required: Signal event name; maximum 100 characters.
    - `parent_event_id` string: Optional parent event id; maximum 128 characters.
    - `event_time` union: Unix timestamp or ISO-8601 date-time. Defaults to receipt time.
      - integer
      - string
    - `event_source` string, uri: Optional absolute source URL.
    - `action_source` string: Optional action source; defaults to website and is limited to 50 characters.
    - `visitor_id` string: Optional visitor identifier; maximum 255 characters.
    - `consent_basis` 'consent', required: Legal basis for processing. Legitimate-interest server revenue retains identity only with admitted global visitor or buyer-country evidence and no opt-out.
    - `consent` object: Consent state supplied with the event.
    - `consent_mode` object: Consent Mode v2 signal values supplied with the event.
    - `tcf` object: TCF v2 data containing string and optional captured_at.
    - `user_data` object: Identity fields accepted by the tracker.
    - `click_ids` object: Advertising click identifiers.
    - `value_data` object: Optional commerce data. Contents accepts at most 50 items and 16 KB serialized.
      - `value` string
      - `currency` string
      - `order_id` string
      - `contents` unknown[]
        - unknown
      - `num_items` integer
  - object
    - `event_id` string: Caller-supplied idempotency key; maximum 128 characters.
    - `event_name` 'signal_verification' | 'consent_withdrawal', required: Signal event name; maximum 100 characters.
    - `parent_event_id` string: Optional parent event id; maximum 128 characters.
    - `event_time` union: Unix timestamp or ISO-8601 date-time. Defaults to receipt time.
      - integer
      - string
    - `event_source` string, uri: Optional absolute source URL.
    - `action_source` string: Optional action source; defaults to website and is limited to 50 characters.
    - `visitor_id` string: Optional visitor identifier; maximum 255 characters.
    - `consent_basis` 'legitimate_interest', required: Legal basis for processing. Legitimate-interest server revenue retains identity only with admitted global visitor or buyer-country evidence and no opt-out.
    - `consent` object: Consent state supplied with the event.
    - `consent_mode` object: Consent Mode v2 signal values supplied with the event.
    - `tcf` object: TCF v2 data containing string and optional captured_at.
    - `user_data` object: Identity fields accepted by the tracker.
    - `click_ids` object: Advertising click identifiers.
    - `value_data` object: Optional commerce data. Contents accepts at most 50 items and 16 KB serialized.
      - `value` string
      - `currency` string
      - `order_id` string
      - `contents` unknown[]
        - unknown
      - `num_items` integer

## Response `200`

Duplicate event accepted idempotently.

- object
  - `event_id` string, required
  - `duplicate` boolean, required

## Other responses

- `202`: New event accepted for processing.
- `401`: Invalid or missing Server secret.
- `422`: Request validation failed.

---

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