Event Ingestion

The event ingestion endpoint is the primary integration point between your application and Synapse. Events trigger flows, update contacts, and drive your communication pipeline.

Endpoint

POST https://synapse-api.pyrx.tech/v1/events

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`X-WORKSPACE-ID`	Yes	Your workspace identifier
`X-API-KEY`	Yes	A `data`-scoped API key

Backward compatibility: The fields user_id and contact_overrides are still accepted as deprecated aliases for external_id and contact respectively. New integrations should use external_id and contact.

Contact Fields

When provided, these fields are upserted on the contact matching external_id. If no contact exists, one is created.

Field	Type	Description
`email`	string	The contact's email address. Required for email delivery.
`first_name`	string	First name. Used in NLT templates as `{the user's First Name}`.
`last_name`	string	Last name.
`phone`	string	Phone number.
`timezone`	string	IANA timezone (e.g., `Asia/Singapore`). Used for send-time optimization.
`locale`	string	Locale code (e.g., `en-SG`, `vi-VN`). Used for localized content.
`properties`	object	Custom key-value pairs. Shallow-merged with existing properties.
`tags`	string[]	Replaces the contact's entire tag list. Use `$add_tags`/`$remove_tags` for surgical updates.
`$add_tags`	string[]	Appends tags to the existing list (duplicates ignored).
`$remove_tags`	string[]	Removes specified tags from the existing list.

Tip

Always include email in contact when sending events for new users. Without an email address, Synapse cannot deliver emails even if a flow matches.

Response

Success (202 Accepted)

json

{

"event_id": "evt_8f14e45f-ceea-467f-a83c-01a01ba3c5db",

"status": "accepted"

}

The event has been accepted and queued for asynchronous processing. Flow matching, trip creation, and email delivery happen in the background.

Error Responses

json

{

"detail": "Missing required field: event_name",

"code": "validation_error"

}

Status	Code	Description
`400`	`validation_error`	Missing or invalid required fields
`401`	`invalid_api_key`	API key is missing, revoked, or invalid
`403`	`insufficient_scope`	API key does not have `data` scope
`403`	`plan_limit_reached`	Monthly events quota exceeded. Upgrade your plan or wait for the next billing cycle.
`409`	`duplicate_event`	An event with this `idempotency_key` was already processed
`429`	`rate_limit_exceeded`	Too many requests -- see Rate Limits

Examples

curl

bash

curl -X POST https://synapse-api.pyrx.tech/v1/events \

-H "Content-Type: application/json" \

-H "X-WORKSPACE-ID: ws_k7x9m2p4" \

-H "X-API-KEY: psk_live_a1b2c3d4e5f67890abcdef1234567890" \

-d '{

"event_name": "claim_submitted",

"external_id": "worker_67890",

"attributes": {

"reference_number": "WIC-2026-0001",

"worker_name": "John Doe",

"incident_date": "2026-03-15T14:30:00+08:00",

"claim_type": "work_injury"

"contact": {

"email": "[email protected]",

"first_name": "John",

"timezone": "Asia/Ho_Chi_Minh",

"$add_tags": ["claimant"]

"idempotency_key": "claim_submitted_WIC-2026-0001"

Python

python

import requests

response = requests.post(

"https://synapse-api.pyrx.tech/v1/events",

headers={

"X-WORKSPACE-ID": "ws_k7x9m2p4",

"X-API-KEY": "psk_live_a1b2c3d4e5f67890abcdef1234567890",

json={

"event_name": "claim_submitted",

"external_id": "worker_67890",

"attributes": {

"reference_number": "WIC-2026-0001",

"worker_name": "John Doe",

"incident_date": "2026-03-15T14:30:00+08:00",

"claim_type": "work_injury",

"contact": {

"email": "[email protected]",

"first_name": "John",

"timezone": "Asia/Ho_Chi_Minh",

"$add_tags": ["claimant"],

"idempotency_key": "claim_submitted_WIC-2026-0001",

)

assert response.status_code == 202

event = response.json()

print(event["event_id"]) # evt_8f14e45f-...

JavaScript

javascript

const response = await fetch("https://synapse-api.pyrx.tech/v1/events", {

method: "POST",

headers: {

"Content-Type": "application/json",

"X-WORKSPACE-ID": "ws_k7x9m2p4",

"X-API-KEY": "psk_live_a1b2c3d4e5f67890abcdef1234567890",

body: JSON.stringify({

event_name: "claim_submitted",

external_id: "worker_67890",

attributes: {

reference_number: "WIC-2026-0001",

worker_name: "John Doe",

incident_date: "2026-03-15T14:30:00+08:00",

claim_type: "work_injury",

contact: {

email: "[email protected]",

first_name: "John",

timezone: "Asia/Ho_Chi_Minh",

$add_tags: ["claimant"],

idempotency_key: "claim_submitted_WIC-2026-0001",

}),

});

const event = await response.json();

console.log(event.event_id); // evt_8f14e45f-...

Batch Ingestion

For high-volume use cases or SDK batch uploads, use the batch endpoint to send up to 50 events in a single request.

POST https://synapse-api.pyrx.tech/v1/events/batch

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`X-WORKSPACE-ID`	Yes	Your workspace identifier
`X-API-KEY`	Yes	A `data`-scoped API key

Request Body

json

{

"events": [

{

"event_name": "page_viewed",

"external_id": "user_12345",

"attributes": {"page": "/pricing", "referrer": "google"}

{

"event_name": "button_clicked",

"external_id": "user_12345",

"attributes": {"button_id": "cta_signup", "page": "/pricing"}

}

]

}

Field	Type	Required	Description
`events`	array	Yes	Array of event objects (1-50 items). Each event follows the same schema as the single event endpoint.

Response (202 Accepted)

json

{

"accepted": 2,

"rejected": 0

}

Field	Type	Description
`accepted`	integer	Number of events successfully queued
`rejected`	integer	Number of events that failed processing

Each event in the batch is processed independently. One failed event does not block others. The source field for batch events is set to sdk.

Note

The batch endpoint checks the monthly events plan limit once before processing. If the limit is reached, the entire batch is rejected with a 403 plan_limit_reached error.

Processing Pipeline

After an event is accepted, Synapse processes it through the following pipeline:

Validate schema -- Verify required fields and attribute types
Upsert contact -- Create or update the contact matching external_id
Store event -- Persist the event to PostgreSQL
Check idempotency -- Skip if this idempotency_key was already processed
Publish to RabbitMQ -- Route to the flow trigger queue for async processing
Flow matching -- Match against all active flows with matching trigger_event
Segment evaluation -- If the flow has a target segment, verify the contact qualifies
Trip creation -- Create a flow trip and execute the flow's steps

Note

Event processing is asynchronous. A 202 Accepted response does not mean the event has been fully processed -- it means it has been durably queued. Use webhooks to track downstream delivery status.

Field	Type	Required	Description
`event_name`	string	Yes	The event type identifier. Use snake_case (e.g., `order_completed`, `claim_submitted`).
`external_id`	string	Yes	Your application's unique user identifier. Used to match or create a contact.
`attributes`	object	No	Arbitrary JSON object containing event-specific data. Defaults to `{}`. Accessible in NLT templates via `{the Amount from the trigger event}`.
`contact`	object	No	Fields to upsert on the contact record. See Contact Fields.
`occurred_at`	datetime	No	When the event occurred (ISO 8601, defaults to server time). Useful for historical imports.
`idempotency_key`	string	No	A unique key to prevent duplicate processing (max 255 chars). See Idempotency.