Events

Track an event

Records one event for an existing contact. Contacts are never created: an unknown contact returns 404. A retry with the same id (or the same contact, name and createdAt when no id is sent) is counted as a duplicate and returns 202. Events for an archived event name are ignored. A new event name creates its definition, up to 200 active names per workspace.

POST

/v2/events

Track an event

curl --request POST \
  --url https://do.featurebase.app/v2/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contact": {
    "email": "jane@example.com",
    "id": "67ec1234abcd5678ef901234",
    "userId": "user_42"
  },
  "createdAt": "2026-10-05T10:00:00Z",
  "id": "evt_01J9Z3",
  "metadata": {
    "plan": "pro",
    "price": {
      "amount": 3499,
      "currency": "EUR"
    },
    "seats": 12
  },
  "name": "updated-plan"
}
'

{
  "accepted": 123,
  "archived": 123,
  "duplicates": 123,
  "errors": [
    {
      "code": "metadata_invalid",
      "index": 123,
      "message": "<string>",
      "param": "metadata.plan"
    }
  ],
  "limitReached": 123,
  "object": "event_receipt"
}

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Body

contactobjectrequired

Who did it. Precedence when several are given: id, then userId, then email. Contacts are never created.

Show child attributes

createdAtstring | integer

When it happened: ISO-8601, or unix seconds. Default: now. Up to 365 days in the past; at most 5 minutes in the future.

Example: 2026-10-05T10:00:00Z

idstring

Your unique ID for this event. Retries with the same ID are ignored (idempotency).

Required string length: 1 - 64

Example: evt_01J9Z3

metadataobject

Up to 20 keys (≤ 4 KB). Values: string (≤ 255), number, boolean, date (ISO-8601, or unix seconds on keys ending in _date), link (http/https string), rich link { url, value }, money { amount (minor units), currency (ISO-4217) }. Keys are case-insensitive and cannot contain . $ ~ ! @ # % ^ & * ' { } | \ "`.

namestringrequired

Event name. 1–100 characters: letters, digits, spaces and _ - . : /, starting with a letter or digit. Case-insensitive. Use past-tense verb-noun names, e.g. updated-plan. The fb: prefix is reserved.

Required string length: 1 - 100

Example: updated-plan

Response

Success

acceptedintegerrequired

Events recorded.

archivedintegerrequired

Events ignored because their event name is archived.

duplicatesintegerrequired

Events ignored because the same event was already recorded (same id, or same contact, name and createdAt).

errorsobject[]required

Show child attributes

limitReachedintegerrequired

Events ignored because the workspace reached its limit of active event names, or of all event names (archived included).

objectenum<string>required

Available options: event_receipt

Still need help? Ask the team