v1

latestOpenAPI 3.1.02026-07-2671538.5 KB

Events

Ingest an event

Send a custom event to Privy. Use events to trigger Flows and other automations from activity in your own systems (a completed purchase, a finished quiz, a loyalty milestone, etc.).

Identify the contact with exactly one of email, phone, or privy_id. If the contact doesn't exist yet, Privy creates one (by email or phone); privy_id must reference an existing contact.

Response status

Unlike most endpoints, a successful ingest returns 200 OK with a status field rather than 201. A payload that fails validation returns 400 Bad Request with a top-level errors array — a different shape from the standard error envelope used for auth and rate-limit errors.

Idempotency

Set the Idempotency-Key header (or an idempotency_key body field; the header wins if both are present) to safely retry. The first request ingests the event; a retry with the same key returns the original response with idempotent_replay: true instead of ingesting a duplicate. Only accepted events are replayed — a rejected payload re-validates on retry.

Limits

The request body must not exceed 256 KB; larger bodies return 413.

Required scope: events_write

post/events

Headers

Idempotency-Keystring

Optional key to safely retry without creating a duplicate event. Use a unique value (such as a UUID) per distinct event. Takes precedence over an idempotency_key body field.

Request body

emailstring email

The contact's email address. Provide exactly one of email, phone, or privy_id to identify the contact.

phonestring

The contact's phone number in E.164 format (+ followed by country code and number). Provide exactly one of email, phone, or privy_id.

privy_idstring

The contact's Privy customer ID (the id returned by the Contacts API, prefixed with cus_). Provide exactly one of email, phone, or privy_id.

event_typestring required

A name for the event. Up to 128 characters; letters, numbers, hyphens, and underscores only. Choose a stable, descriptive name — you'll use it to trigger Flows (e.g. purchase_completed, quiz_finished).

event_timestring date-time

ISO 8601 date-time the event occurred. Must be UTC — end the timestamp with Z (or a zero offset). Optional; defaults to the time Privy received the event.

event_dataobject

Arbitrary key-value data describing the event. Values may be strings, numbers, booleans, null, objects, or arrays. Objects and arrays may be nested up to 10 levels deep. Stored and made available to downstream automations verbatim.

idempotency_keystring

Optional key to safely retry a request without creating a duplicate event. Prefer the Idempotency-Key header; if both are sent, the header wins. See the endpoint description for replay semantics.

Example request

{
  "email": "shopper@example.com",
  "phone": "+15551234567",
  "privy_id": "cus_a1b2c3d4e5f6g7h8",
  "event_type": "purchase_completed",
  "event_time": "2026-06-15T10:30:00Z",
  "event_data": {
    "order_id": "ORD-12345",
    "total": 99.99,
    "currency": "USD",
    "items": [
      {
        "sku": "SKU-1",
        "quantity": 2
      }
    ]
  },
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
}

Response

The event was accepted, or replayed from a prior request with the same idempotency key.

event_idstring

Privy's identifier for the stored event.

status'accepted'

idempotent_replayboolean

Present and true only when this response was served from a prior request with the same idempotency key, rather than ingesting a new event.

Example response

{
  "event_id": "507f1f77bcf86cd799439011",
  "status": "accepted",
  "idempotent_replay": true
}