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
event_type you send. A successful 200 response means the event was accepted
for processing — it does not guarantee a specific automation ran.Authorizations
Send either an API token or an OAuth access token as
Authorization: Bearer <token>. See the Authentication page for details.
Headers
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.
Body
An event to ingest. You must identify the contact with exactly one of
email, phone, or privy_id, and provide an event_type.
Everything else is optional. Unknown top-level keys are ignored — put your
own data under event_data.
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).
128^[A-Za-z0-9_-]+$"purchase_completed"
The contact's email address. Provide exactly one of email, phone,
or privy_id to identify the contact.
"shopper@example.com"
The contact's phone number in E.164 format (+ followed by country
code and number). Provide exactly one of email, phone, or privy_id.
"+15551234567"
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.
"cus_a1b2c3d4e5f6g7h8"
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.
"2026-06-15T10:30:00Z"
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.
{
"order_id": "ORD-12345",
"total": 99.99,
"currency": "USD",
"items": [{ "sku": "SKU-1", "quantity": 2 }]
}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.
"550e8400-e29b-41d4-a716-446655440000"
Response
The event was accepted, or replayed from a prior request with the same idempotency key.
The event was accepted (or replayed from a prior identical request).
Privy's identifier for the stored event.
"507f1f77bcf86cd799439011"
accepted "accepted"
Present and true only when this response was served from a prior
request with the same idempotency key, rather than ingesting a new event.
true