Key events API
Make, change and read your key events: the actions that matter to your business. Every reply has the shape { data, error, metadata }. Send x-api-key with a workspace key. Making, changing and deleting need a workspace admin.
/api/conversions is the older name for the same routes. It still works and keeps its older reply shape ({ conversions }, { conversion }).
List key events
/api/key-eventsEvery key event, in funnel order
{
"data": {
"keyEvents": [
{
"id": "conv_lead",
"name": "Lead captured",
"category": "lead",
"sources": [
{ "type": "custom_event", "eventName": "application_submitted" },
{ "type": "custom_event", "eventName": "audit_booked", "where": [{ "fieldPath": "plan", "operator": "equals", "value": "pro" }] }
],
"counts": "Each time your site or app sends application_submitted; or each time your site or app sends audit_booked, when plan is pro",
"order": 1,
"isCurrentGoal": true,
"entityScope": "person",
"definitionVersion": 2,
"definitionHistory": [
{ "version": 1, "sources": [{ "type": "custom_event", "eventName": "application_submitted" }], "entityScope": "person", "changedAt": "2026-11-02T15:04:00.000Z", "changedBy": "dana@example.com" }
],
"stored": true
}
]
},
"error": null,
"metadata": { "workspace_key": "your-workspace" }
}
stored is false for a key event Apex still reads from your older goals list. Changing it saves it as a key event.
Add ?reached_since=2026-11-01T00:00:00Z and each key event also carries reachedSince: how many people first reached it since then (companies, for a key event that counts companies).
Make a key event
/api/key-eventsMake a key event. Workspace admin.
| Parameter | Type | Description |
|---|---|---|
namerequired | string | What the business calls it, e.g. Lead captured |
sourcesrequired | array | 1 to 20 events that reach it. Any one is enough. |
sources[].typerequired | string | custom_event (a named event) or form_submit (a form on your site) |
sources[].event_name | string | For custom_event: the event's name |
sources[].selector | string | For form_submit: one form, as #id. Leave out for any form. |
sources[].target_url | string | For form_submit: the page the form is on. Leave out for any page. |
sources[].where | array | Up to 10 conditions on the event's data. All must hold. |
sources[].where[].field_pathrequired | string | A field on the event, dots for nested ones (plan, order.channel) |
sources[].where[].operatorrequired | string | equals, not_equals, in, exists or not_exists |
sources[].where[].value | string | number | boolean | array | One value for equals and not_equals, a list for in, none for exists |
category | string | purchase, lead, qualified_lead, activation, signup, subscribe, add_to_cart, engagement or other. Sets its place in the funnel. |
entity_scope | string | person (default) or account: a company reaches it when its first person does |
description | string | A note for your team |
template | string | The template it follows, e.g. lead_captured |
Returns 201 with { data: { keyEvent } }. Clicks and page views are refused: outside an experiment Apex counts named events and form submissions. camelCase keys (eventName, fieldPath) are accepted too.
To count a Milestone as a key event, use milestone_adopted with the Milestone's id as a condition: { "type": "custom_event", "event_name": "milestone_adopted", "where": [{ "field_path": "milestone_id", "operator": "equals", "value": "<milestone id>" }] }. The person reaches it at the time they finished the Milestone.
Read one key event
/api/key-events/{id}One key event, its versions, and the ad platform conversions linked to it
Returns { data: { keyEvent, links } }, or 404 with "Key event not found".
Change a key event
/api/key-events/{id}Rename it, or change what reaches it. Workspace admin.
Takes the same fields as making one, all optional, plus is_current_goal: true to make it the main key event, the one Attribution leads with.
A rename keeps its version. New sources, new conditions or a new entity_scope make the next version: people already counted keep the version they reached, and the old version stays in definitionHistory with who changed it.
Delete a key event
/api/key-events/{id}Delete a key event. Workspace admin.
Returns { data: { deleted: true } }. A key event from your older goals list is archived there too, so it doesn't come back. Segments, journeys, campaign steps, ad platform sends and Targets that use it stop counting it. If what counts has changed, change the key event instead, so its history stays.
Who reached it
/api/key-events/{id}/reachedWho reached a key event, when, and how
| Parameter | Type | Description |
|---|---|---|
scope | string | person (default) or account: each company once, from its first person |
start | string | ISO date. First times on or after it. |
end | string | ISO date. First times on or before it. |
version | number | Only people who reached this version |
limit | number | Rows to return, 100 by default, up to 1000. Totals always count everyone. |
{
"data": {
"keyEventId": "conv_lead",
"scope": "person",
"total": 2,
"live": 1,
"history": 1,
"reached": [
{ "contactId": "c_81", "firstAt": "2026-11-12T18:20:00.000Z", "via": "live", "eventId": "evt_9f2", "definitionVersion": 2, "sourceIndex": 1 },
{ "contactId": "c_14", "firstAt": "2026-10-03T09:11:00.000Z", "via": "history", "definitionVersion": 1 }
]
},
"error": null,
"metadata": { "workspace_key": "your-workspace", "definition_version": 2, "truncated": false }
}
via: "live" means Apex saw it happen. via: "history" means Apex found it later, when the key event was made or changed; those people are never sent to ad platforms or journeys because of it. sourceIndex is which of the key event's events reached it, counting from 0.