Events

Events let you record actions your contacts take — page views, purchases, feature usage, and any other custom activity. Events can trigger sequence enrolments and are used in segment rules.

Track event

POST /api/events

Records a custom event against a contact. The contact is identified by email and must already exist — if no contact with that email exists, the request fails with CONTACT_NOT_FOUND.

Request body

Field	Type	Required	Description
`email`	string	Yes	The email of the contact the event belongs to.
`name`	string	Yes	The event name (e.g. `page_viewed`, `purchase_completed`).
`properties`	object	No	Arbitrary key-value data associated with the event.
`timestamp`	string	No	ISO 8601 timestamp. Defaults to the current time if omitted. Must not be more than 5 minutes in the future.
`updateContact`	boolean	No	Whether to update the contact's derived properties from this event. Defaults to `true`.

Response

Returns the created event wrapped alongside the resolved contactId and any sequences the event triggered. When updateContact is true, the updated contact is also included.

{
  "event": {
    "eventId": "evt_01H9...",
    "name": "purchase_completed",
    "properties": {
      "product": "Pro Plan",
      "amount": 49.00,
      "currency": "GBP"
    },
    "timestamp": "2025-09-15T14:20:00.000Z",
    "processedSequences": []
  },
  "contactId": "cnt_01H8MZXK...",
  "triggeredSequences": []
}

Errors

Code	Description
`VALIDATION_ERROR`	Missing event name or email, or a `timestamp` more than 5 minutes in the future.
`CONTACT_NOT_FOUND`	No contact exists for the provided `email`.

Examples

curl -X POST https://api.kraiter.com/api/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "name": "purchase_completed",
    "properties": {
      "product": "Pro Plan",
      "amount": 49.00,
      "currency": "GBP"
    }
  }'

const result = await kraiter.events.track({
  email: "alice@example.com",
  name: "purchase_completed",
  properties: {
    product: "Pro Plan",
    amount: 49.0,
    currency: "GBP",
  },
});

Backdating events

To record an event that happened in the past, provide the timestamp field:

curl -X POST https://api.kraiter.com/api/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "name": "signed_up",
    "timestamp": "2025-08-01T09:00:00.000Z"
  }'

const result = await kraiter.events.track({
  email: "alice@example.com",
  name: "signed_up",
  timestamp: "2025-08-01T09:00:00.000Z",
});

Event naming conventions

Use snake_case for event names. Keep them descriptive but concise:

Good	Avoid
`page_viewed`	`PageViewed`
`purchase_completed`	`purchase`
`feature_activated`	`user did a thing`
`subscription_cancelled`	`sub_cancel_v2`

Event names are case-sensitive. page_viewed and Page_Viewed are treated as separate events.