Events

An event is something a person or object did at a point in time — a payment_made, a checkout_started, a loan_disbursed. Unlike people and custom objects (which you upsert to a current state), events are an append-only log: each one is recorded once and read back later, individually or as a filtered, paginated stream.

Anatomy of an event

Field	Required	Notes
`name`	✅	Letters, numbers, and underscores only — no spaces or symbols.
`externalId`	✅	Your stable id for this event. It’s the idempotency key: re-sending the same one returns `created: false` instead of duplicating.
`timestamp`	—	ISO 8601 event time. Defaults to now() when omitted.
`personExternalId`	—	The person subject.
`customObjectType` + `customObjectExternalId`	—	The object subject (sent together).
`properties`	—	Free-form JSON describing the event.

At least one subject is required: personExternalId, or the customObjectType + customObjectExternalId pair. You may set both (a person event about an object).

Subjects are referenced by your external ids. They’re stored as-is and Boom resolves the internal link best-effort — recording an event for a person who hasn’t synced yet still succeeds, and the link is back-stitched later. A missing subject never fails the request.

Record an event

curl -X POST "$BASE/events" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"payment_made","externalId":"evt_123","personExternalId":"user_42","properties":{"amount":1200}}'

Returns { "created": true, "eventId": "evt_db_1" }. For historical loads, Record events in bulk accepts up to 1000 per request. Bulk ingest is treated as backfill — it does not fire journey enrollment, so use the single endpoint for real-time, journey-triggering events.

Read events back

Fetch one by the externalId you supplied:

curl "$BASE/events/evt_123" -H "Authorization: Bearer $BOOM_KEY"

Or list them, newest first, with optional filters (combined with AND):

# every payment_made for one person, in June
curl "$BASE/events?name=payment_made&personExternalId=user_42&start=2026-06-01T00:00:00Z&end=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer $BOOM_KEY"

Filters match the external references you supplied at ingest, so events recorded before their subject synced are still returned.

Pagination

Every list endpoint (events, people, custom objects) is cursor-paginated. A response carries next_cursor; pass it back as ?cursor= to get the next page, and loop until next_cursor is null:

GET /events?limit=1000              → { data:[1000], next_cursor:"c1" }
GET /events?limit=1000&cursor=c1    → { data:[1000], next_cursor:"c2" }
GET /events?limit=1000&cursor=c2    → { data:[42],   next_cursor:null }   # done

limit defaults to 100 (max 1000). The cursor is opaque and stable under concurrent writes — no skipped or duplicated rows.

Quickstart

Record your first event alongside people and objects.

Relationship types

Model the links between the people and objects your events reference.

Getting started

MCP

Data sources

Concepts

Anatomy of an event

Record an event

Read events back

Quickstart

Relationship types

​Anatomy of an event

​Record an event

​Read events back

​Pagination

​Related

Quickstart

Relationship types

Anatomy of an event

Record an event

Read events back

Pagination

Related