Track events from your backend

The server-side half of track(): a batch of up to 100 events (256 KiB) that your own backend sends, each one naming the contact it belongs to.

It exists for the facts that never happen in a browser — a payment confirmed by a webhook, a contract countersigned, an export a worker finished. Those are exactly the facts an onboarding step is usually waiting on, and until this door existed they could only arrive through POST /v1/events, which cannot name anybody: an event with no contact advances no checklist for anybody, silently.

Every line must name a contact, with external_id or contact_id — one of the two. Both on one line is ambiguous_contact and neither is contact_required: a line naming two people is one we would have to guess about, and a line naming nobody is the failure this endpoint exists to end. The key’s environment scopes the lookup, so a live external_id sent with a test key resolves to nothing and comes back as unknown_contact.

A line may also name the TEAM it happened inside, with customer_id or customer_external_id — one of the two, never both (ambiguous_customer). It is optional, and leaving it out is an answer: the fact is then the person’s own, and the staff dossier lists it whichever of their teams somebody is reading. A team you name and we cannot resolve in this environment is unknown_customer and the line is refused rather than filed as teamless — saying which team and being ignored is worse than not saying. Membership is not checked: your backend is the authority on which of your teams a fact belongs to, the same claim that lets it name the contact.

It never creates a contact. Identify is one call away (POST /v1/contacts), and an ingest endpoint that minted contacts would add rows to your active-contact meter — which is billed — as a side effect of sending analytics.

202 means accepted, never durable, and validation is per event — both exactly as POST /v1/events describes them. The line codes are that endpoint’s plus the two above: invalid_id, reserved_name (the $ prefix is UserKit’s own namespace, refused here as firmly as anywhere), invalid_name, properties_too_large, invalid_properties, invalid_occurred_at, occurred_at_out_of_range, contact_required, ambiguous_contact, unknown_contact, ambiguous_customer, unknown_customer.

Send an Idempotency-Key if a client, a queue or a deploy might retry this call — the retry replays the first response instead of counting a funnel twice.

Rate limited per key (1000/min) with a 3000/min per-environment ceiling behind it, and the same 6000/min analytics ceiling POST /v1/events spends.