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

GET/api/key-events

Every key event, in funnel order

curl https://app.apex.inc/api/key-events \ -H "x-api-key: apex_sk_..."
{
  "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

POST/api/key-events

Make a key event. Workspace admin.

ParameterTypeDescription
namerequiredstringWhat the business calls it, e.g. Lead captured
sourcesrequiredarray1 to 20 events that reach it. Any one is enough.
sources[].typerequiredstringcustom_event (a named event) or form_submit (a form on your site)
sources[].event_namestringFor custom_event: the event's name
sources[].selectorstringFor form_submit: one form, as #id. Leave out for any form.
sources[].target_urlstringFor form_submit: the page the form is on. Leave out for any page.
sources[].wherearrayUp to 10 conditions on the event's data. All must hold.
sources[].where[].field_pathrequiredstringA field on the event, dots for nested ones (plan, order.channel)
sources[].where[].operatorrequiredstringequals, not_equals, in, exists or not_exists
sources[].where[].valuestring | number | boolean | arrayOne value for equals and not_equals, a list for in, none for exists
categorystringpurchase, lead, qualified_lead, activation, signup, subscribe, add_to_cart, engagement or other. Sets its place in the funnel.
entity_scopestringperson (default) or account: a company reaches it when its first person does
descriptionstringA note for your team
templatestringThe template it follows, e.g. lead_captured
curl -X POST https://app.apex.inc/api/key-events \ -H "Content-Type: application/json" \ -H "x-api-key: apex_sk_..." \ -d '{ "name": "Lead captured", "category": "lead", "sources": [ { "type": "custom_event", "event_name": "application_submitted" }, { "type": "custom_event", "event_name": "audit_booked", "where": [{ "field_path": "plan", "operator": "equals", "value": "pro" }] } ] }'

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

GET/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

PATCH/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.

curl -X PATCH https://app.apex.inc/api/key-events/conv_lead \ -H "Content-Type: application/json" \ -H "x-api-key: apex_sk_..." \ -d '{ "entity_scope": "account" }'

Delete a key event

DELETE/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

GET/api/key-events/{id}/reached

Who reached a key event, when, and how

ParameterTypeDescription
scopestringperson (default) or account: each company once, from its first person
startstringISO date. First times on or after it.
endstringISO date. First times on or before it.
versionnumberOnly people who reached this version
limitnumberRows 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.