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. You can identify the contact by contactId or email. If you provide an email that does not match an existing contact, the event is still recorded and will be associated when a contact with that email is created.

Request body

Field	Type	Required	Description
`name`	string	Yes	The event name (e.g. `page_viewed`, `purchase_completed`).
`contactId`	string	Conditional	The contact ID. Required if `email` is not provided.
`email`	string	Conditional	The contact's email. Required if `contactId` is not provided.
`properties`	object	No	Arbitrary key-value data associated with the event.
`timestamp`	string	No	ISO 8601 timestamp. Defaults to the current time if omitted.

You must provide either contactId or email, but not both.

Response

Returns the created event.

{
  "id": "evt_01H9...",
  "name": "purchase_completed",
  "contactId": "cnt_01H8MZXK...",
  "properties": {
    "product": "Pro Plan",
    "amount": 49.00,
    "currency": "GBP"
  },
  "timestamp": "2025-09-15T14:20:00.000Z",
  "createdAt": "2025-09-15T14:20:00.123Z"
}

Errors

Code	Description
`VALIDATION_ERROR`	Missing event name, or neither `contactId` nor `email` provided.
`NOT_FOUND`	The specified `contactId` does not exist.

Examples

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

const event = await kraiter.events.track({
  name: "purchase_completed",
  contactId: "cnt_01H8MZXK...",
  properties: {
    product: "Pro Plan",
    amount: 49.0,
    currency: "GBP",
  },
});

Identifying by email

When you do not have the contact ID readily available, you can use the contact's email instead:

curl -X POST https://api.kraiter.com/api/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "page_viewed",
    "email": "alice@example.com",
    "properties": { "url": "/pricing" }
  }'

const event = await kraiter.events.track({
  name: "page_viewed",
  email: "alice@example.com",
  properties: { url: "/pricing" },
});

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 '{
    "name": "signed_up",
    "contactId": "cnt_01H8MZXK...",
    "timestamp": "2025-08-01T09:00:00.000Z"
  }'

const event = await kraiter.events.track({
  name: "signed_up",
  contactId: "cnt_01H8MZXK...",
  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.

Events

On this page