API reference

Events

Record custom events to power contact timelines and trigger automations.

An event is a named action, optionally tied to a contact by email — like user.signed_up or order.completed. Events are the trigger primitive behind automations.

The event object#

json

{
  "id": "event_7x8y9z",
  "name": "user.signed_up",
  "contact_id": "contact_a1b2c3",
  "created_at": "2026-07-10T10:30:45.123Z"
}

Record an event#

POST/v1/events

If email matches a known contact, the event is linked to it. If the email is unknown the event is still recorded, with contact_id set to null.

Body parameters

namestringRequired

The event name, e.g. order.completed.

emailstringOptional

Email of the contact to attribute the event to.

dataobjectOptional

Arbitrary JSON payload for the event, e.g. { "amount": 4900, "currency": "usd" }.

curl -X POST https://app.getdeckle.com/api/v1/events \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "order.completed", "email": "jane@example.com",
        "data": { "amount": 4900 } }'

Events drive automations

Recording an event enrolls the matching contact into any live automation triggered by that event, and wakes any automation runs that are waiting for it. A missing name returns 422.