Skip to content

Your First API Call

Send your first event to Synapse in under two minutes. This guide assumes you have a workspace and an API key -- see Authentication if you need to set those up.

Prerequisites

  • A Synapse workspace ID (e.g., ws_k7x9m2p4)
  • A data-scoped API key (e.g., psk_live_a1b2c3d4...)

Send an Event with 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": "signup_completed",
"external_id": "user_12345",
"attributes": {
"plan": "starter",
"source": "landing_page"
},
"contact": {
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe"
}
}'

Response

json
{
"event_id": "evt_8f14e45f-ceea-467f-a83c-01a01ba3c5db",
"status": "accepted"
}

A 202 Accepted response means the event has been received and queued for processing. Synapse will match it against active flows asynchronously.

Send an Event with Python

python
import requests
 
response = requests.post(
"https://synapse-api.pyrx.tech/v1/events",
headers={
"Content-Type": "application/json",
"X-WORKSPACE-ID": "ws_k7x9m2p4",
"X-API-KEY": "psk_live_a1b2c3d4e5f67890abcdef1234567890",
},
json={
"event_name": "signup_completed",
"external_id": "user_12345",
"attributes": {
"plan": "starter",
"source": "landing_page",
},
"contact": {
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
},
},
)
 
print(response.status_code) # 202
print(response.json()) # {"event_id": "evt_...", "status": "accepted"}

Send an Event with 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: "signup_completed",
external_id: "user_12345",
attributes: {
plan: "starter",
source: "landing_page",
},
contact: {
email: "[email protected]",
first_name: "Jane",
last_name: "Doe",
},
}),
});
 
const data = await response.json();
console.log(data); // { event_id: "evt_...", status: "accepted" }

What Happens Next

Once Synapse accepts your event:

  1. Contact upsert -- If a contact with external_id: "user_12345" does not exist, Synapse creates one using the contact fields. If it exists, those fields are merged.
  2. Flow matching -- Synapse checks all active flows for a trigger_event matching "signup_completed". Any matching flows evaluate their trigger conditions.
  3. Trip creation -- For each matching flow, a flow trip is created for this contact. The trip executes the flow's steps (send email, wait, condition, etc.).
  4. Email delivery -- If a step sends an email, the NLT template engine renders the template with the contact and event data, then delivers it via Resend.
Tip

Use the test environment API key (psk_test_...) during development. Events are processed normally, but emails are logged without being sent.

Error Handling

StatusMeaning
202 AcceptedEvent queued for processing
400 Bad RequestMissing required fields (event_name, external_id) or invalid schema
401 UnauthorizedInvalid or missing API key
403 ForbiddenAPI key lacks data scope
409 ConflictDuplicate idempotency_key (event already processed)
429 Too Many RequestsRate limit exceeded
json
{
"detail": "Missing required field: event_name",
"code": "validation_error"
}

Next Steps

  • Event Schema -- Learn about attribute conventions and contact fields
  • Idempotency -- Prevent duplicate event processing
  • API Keys -- Understand key scopes and rotation