Events

Events record things that happen to a customer, such as a purchase, an abandoned cart, a login or a support ticket. They appear on the record's timeline, can start automations, and can be used in segments ("placed an order in the last 30 days").

Register the event type first

The API only accepts registered event types, so a typo can't pollute your data. An event type has a key (use noun.verb, e.g. order.placed), the object it happens to (usually contact) and the fields its payload carries. Register types in the app under Settings → Events, or with the Event types endpoints in the API reference.

Sending an unknown event type returns 404.

Send an event

curl -X POST https://crm.codefab.dev/api/v1/events \
-H "X-API-Key: $CRM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"eventType": "cart.abandoned",
"subject": { "match": { "email": "anna.svensson@example.com" } },
"payload": { "cartValue": 849, "currency": "SEK", "items": 3 },
"occurredAt": "2026-09-25T09:41:00Z"
}'

occurredAt is optional and defaults to now. Set it when you send events after the fact.

Pointing at the right record

subject says which record the event belongs to. Use exactly one of:

FieldMatches
recordIdThe CRM's own record ID
externalIdYour ID, as used in upserts
matchA unique field, e.g. { "email": "anna.svensson@example.com" }

If no record matches, the request fails. Create or upsert the record first.

Payload validation

The payload is checked against the fields registered for the event type and normalised (numbers, dates, booleans). Invalid payloads are rejected with a 400 listing each field.

Sending many events

POST /events:batch accepts a list of events and returns a result per item, so one bad event never aborts the rest:

JSON
{
"accepted": 2,
"failed": 1,
"results": [
{ "index": 0, "status": "accepted", "timelineEventId": "0d6f7c1a-2b3c-4d5e-8f90-1a2b3c4d5e6f" },
{ "index": 1, "status": "accepted", "timelineEventId": "7e1d2c3b-4a59-4687-9a0b-c1d2e3f4a5b6" },
{ "index": 2, "status": "failed", "error": "No record matches the subject." }
]
}

Old events don't start automations

An event whose occurredAt is more than 24 hours in the past is recorded on the timeline and counts in segments, but it doesn't start automations: a purchase from last month shouldn't trigger today's "thanks for your order". The X-Backfill: true header (see Records) does the same for any request.

Sending an event exactly once

Give each event your own eventId, for example order-10442-placed. If the same eventId arrives again (a retry after a timeout, a re-sent batch), nothing new is recorded and no automation starts a second time; the answer points at the event recorded the first time.