SonarSend API Endpoints Events

Events

The account-wide event feed, and custom event ingestion.

1 endpoint Base URL · https://api.sonarsend.com Auth · X-API-Key

Record a custom event

POST /t/{slug}/api/events

Records a server-side event for a contact — a purchase, a renewal, a payment failure, a meeting booked: the things your backend knows that the tracking snippet cannot see. The event is stored against the contact and drives scoring, segmentation and sequence triggers.

Identify the contact with contact_id or contact_email (one is required). By default an unknown contact is 404 CONTACT_NOT_FOUND; enable auto_create_on_event in the workspace settings to have a minimal contact created from the email instead.

event_name is the label the event is grouped under. type is an optional activity-type hint: when set, the server normalises known property aliases and returns warnings for recommended properties you left out — the event is still recorded. occurred_at backdates the event; omit it for now. Returns 202: the event is accepted, not yet fully classified.

Body

event_namestringRequired

What happened, e.g. Renewed Plan. The grouping key in the catalog.

contact_emailemail

Identify the contact by email instead. With auto_create_on_event, an unknown address creates a contact.

contact_iduuid

The contact this event belongs to. One of contact_id / contact_email is required.

occurred_atdate-time

When it happened (ISO 8601). Defaults to now.

propertiesobject

Arbitrary structured payload for the event.

typestring

Optional activity-type hint (e.g. purchase). Drives alias normalisation and the warnings in the response.

Returns

contact_iduuid

The contact the event was attached to (the one created, when auto-create fired).

event_iduuid

The recorded event's ID.

warningsstring[]

Recommended properties the type hint expected but did not find. Advisory — the event was still recorded.

Responses

202

The event was accepted. warnings is present only when a type hint flagged missing recommended properties.

400

The request failed validation, or a referenced record was rejected.

404

The tenant slug, or the record the path names, does not exist.

Request

curl -X POST "https://api.sonarsend.com/t/acme/api/events" \
  -H "X-API-Key: $SONARSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "Acme onboarding",
    "contact_id": "9c21895d-57f0-4a15-a1df-4dc6835d4f80",
    "contact_email": "jamie@example.com",
    "type": "string",
    "properties": {},
    "occurred_at": "2026-01-15T09:30:00.000Z"
  }'

const res = await fetch('https://api.sonarsend.com/t/acme/api/events', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SONARSEND_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "event_name": "Acme onboarding",
    "contact_id": "9c21895d-57f0-4a15-a1df-4dc6835d4f80",
    "contact_email": "jamie@example.com",
    "type": "string",
    "properties": {},
    "occurred_at": "2026-01-15T09:30:00.000Z"
  }),
});

const data = await res.json();

Response 202

{
  "event_id": "9c21895d-57f0-4a15-a1df-4dc6835d4f80",
  "contact_id": "9c21895d-57f0-4a15-a1df-4dc6835d4f80",
  "warnings": [
    "string"
  ]
}