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:
| Field | Matches |
|---|---|
recordId | The CRM's own record ID |
externalId | Your ID, as used in upserts |
match | A 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:
{"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.