Identify contacts and report automation events

Events report named customer activity such as purchase completed or cart abandoned. Convert persists the occurrence against one contact and queues automation processing. Event/identify/trigger routes are available under both /api/v1 and /v1.

Identify the contact

POST /api/v1/identify requires contacts:write. Supply contact with a numeric id, stable external_id/external_customer_id, email, or phone/phone_number. Include supported profile data and custom fields when enriching the record.

123456789{
  "contact": {
    "external_id": "customer-1042",
    "email": "[email protected]",
    "first_name": "Ada",
    "custom_fields": {"tier": "gold"},
    "timezone": "Africa/Lagos"
  }
}

HTTP 200 returns success, numeric contact_id, and external ID. If several rows share an email/phone, supply a stable ID. Identifiers that refer to different contacts are rejected instead of guessed.

Report a named event

POST /api/v1/events requires events:write. The body contains event, a contact identifier object, immutable occurrence properties, optional event_id, and optional ISO-8601 occurred_at.

123456{
  "event": "purchase_completed",
  "event_id": "purchase-ORD-1042",
  "contact": {"external_id": "customer-1042"},
  "properties": {"order_id": "ORD-1042", "total": 24000, "currency": "NGN"}
}

HTTP 202 returns received, the Convert event public ID, and duplicate. It acknowledges persisted/queued intake, not completion of every automation step. Use a stable event ID or idempotency key when retrying the same occurrence.

Current payload limits: request body 128 KB; properties at most 100 keys and 64 KB. occurred_at cannot be more than five minutes in the future. Identify custom fields also have bounded count/size.

Trigger a published automation

POST /api/v1/automations/:automation_id/trigger requires automations:write. The automation must be active, owned by the workspace, and published with an API trigger. Supply contact, optional data properties, and optional event_id.

12345{
  "contact": {"external_id": "customer-1042"},
  "event_id": "welcome-customer-1042",
  "data": {"source": "account_signup"}
}

Follow the journey

Match trigger names and audiences exactly. An event is associated with a contact; the automation then applies its configured list and entry rules. Inspect the event and execution history if intake succeeds but no journey starts.

Next: review automations, workflow steps, and idempotency.

Event examples can trigger live workflows. Send them to a staging contact/workspace before connecting production activity.