curl --request POST \
--url https://api.privy.com/v1/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "shopper@example.com",
"event_type": "purchase_completed",
"event_time": "2026-06-15T10:30:00Z",
"event_data": {
"order_id": "ORD-12345",
"total": 99.99,
"currency": "USD"
}
}
'import requests
url = "https://api.privy.com/v1/events"
payload = {
"email": "shopper@example.com",
"event_type": "purchase_completed",
"event_time": "2026-06-15T10:30:00Z",
"event_data": {
"order_id": "ORD-12345",
"total": 99.99,
"currency": "USD"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
email: 'shopper@example.com',
event_type: 'purchase_completed',
event_time: '2026-06-15T10:30:00Z',
event_data: {order_id: 'ORD-12345', total: 99.99, currency: 'USD'}
})
};
fetch('https://api.privy.com/v1/events', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.privy.com/v1/events",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => 'shopper@example.com',
'event_type' => 'purchase_completed',
'event_time' => '2026-06-15T10:30:00Z',
'event_data' => [
'order_id' => 'ORD-12345',
'total' => 99.99,
'currency' => 'USD'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.privy.com/v1/events"
payload := strings.NewReader("{\n \"email\": \"shopper@example.com\",\n \"event_type\": \"purchase_completed\",\n \"event_time\": \"2026-06-15T10:30:00Z\",\n \"event_data\": {\n \"order_id\": \"ORD-12345\",\n \"total\": 99.99,\n \"currency\": \"USD\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.privy.com/v1/events")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"shopper@example.com\",\n \"event_type\": \"purchase_completed\",\n \"event_time\": \"2026-06-15T10:30:00Z\",\n \"event_data\": {\n \"order_id\": \"ORD-12345\",\n \"total\": 99.99,\n \"currency\": \"USD\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.privy.com/v1/events")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"shopper@example.com\",\n \"event_type\": \"purchase_completed\",\n \"event_time\": \"2026-06-15T10:30:00Z\",\n \"event_data\": {\n \"order_id\": \"ORD-12345\",\n \"total\": 99.99,\n \"currency\": \"USD\"\n }\n}"
response = http.request(request)
puts response.read_body{
"event_id": "507f1f77bcf86cd799439011",
"status": "accepted"
}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
curl --request POST \
--url https://api.privy.com/v1/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "shopper@example.com",
"event_type": "purchase_completed",
"event_time": "2026-06-15T10:30:00Z",
"event_data": {
"order_id": "ORD-12345",
"total": 99.99,
"currency": "USD"
}
}
'import requests
url = "https://api.privy.com/v1/events"
payload = {
"email": "shopper@example.com",
"event_type": "purchase_completed",
"event_time": "2026-06-15T10:30:00Z",
"event_data": {
"order_id": "ORD-12345",
"total": 99.99,
"currency": "USD"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
email: 'shopper@example.com',
event_type: 'purchase_completed',
event_time: '2026-06-15T10:30:00Z',
event_data: {order_id: 'ORD-12345', total: 99.99, currency: 'USD'}
})
};
fetch('https://api.privy.com/v1/events', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.privy.com/v1/events",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => 'shopper@example.com',
'event_type' => 'purchase_completed',
'event_time' => '2026-06-15T10:30:00Z',
'event_data' => [
'order_id' => 'ORD-12345',
'total' => 99.99,
'currency' => 'USD'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.privy.com/v1/events"
payload := strings.NewReader("{\n \"email\": \"shopper@example.com\",\n \"event_type\": \"purchase_completed\",\n \"event_time\": \"2026-06-15T10:30:00Z\",\n \"event_data\": {\n \"order_id\": \"ORD-12345\",\n \"total\": 99.99,\n \"currency\": \"USD\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.privy.com/v1/events")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"shopper@example.com\",\n \"event_type\": \"purchase_completed\",\n \"event_time\": \"2026-06-15T10:30:00Z\",\n \"event_data\": {\n \"order_id\": \"ORD-12345\",\n \"total\": 99.99,\n \"currency\": \"USD\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.privy.com/v1/events")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"shopper@example.com\",\n \"event_type\": \"purchase_completed\",\n \"event_time\": \"2026-06-15T10:30:00Z\",\n \"event_data\": {\n \"order_id\": \"ORD-12345\",\n \"total\": 99.99,\n \"currency\": \"USD\"\n }\n}"
response = http.request(request)
puts response.read_body{
"event_id": "507f1f77bcf86cd799439011",
"status": "accepted"
}event_type you send. A successful 200 response means the event was accepted
for processing — it does not guarantee a specific automation ran.Authorizations
Headers
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"
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 }]
}
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).
Was this page helpful?