Track an event

POST/v1/events

Any key — pk_… is accepted, so this is safe in client code · Base URL https://api.volanea.com

Ingest a product event for a contact (auto-created if unknown). Accepts the public key (pk_…), so it is safe to call from client-side code. Names with the email./contact./segment./workflow. prefixes are reserved for system events. Events feed segments, workflow triggers, and webhooks.

Body

Required · application/json

namestringrequired
Your event name, e.g. `user.signup` (reserved prefixes excluded).
emailemailrequired
The contact the event belongs to.
dataobject
Properties of the event — what happened. Point-in-time; never applied to the contact.
contactobject
Who the contact is. Applied to the contact record, so a workflow triggered by this event can personalise its email with `{{firstName}}`. Omit a field to leave the existing value untouched; omit the whole object and the contact is created with only an address.
- firstNamestring
- lastNamestring
- localestring
- dataobject
  Custom contact fields, merged into the contact's existing `data`.

Response

Event recorded, with what it set off.

eventIdstringrequired
contactIdstringrequired
The contact the event was attributed to, created if it did not exist.
triggeredobject[]required
The active workflows this event just handed to the automation engine. **An empty array means nothing matched** — that is the point of the field. Firing automations is what this endpoint is for, and before this existed the only way to find out whether anything happened was to list every workflow and compare trigger strings by hand; a typo in an event name looked exactly like a working integration.
- workflowIdstringrequired
- namestringrequired
- triggerstringrequired
  The workflow's trigger string that this event matched.
- statusenumrequired
  dispatched
skippedobject[]required
Workflows whose trigger matched but that are `draft` or `paused`, so nothing ran. Check this before concluding your trigger string is wrong: an empty `triggered` with a non-empty `skipped` means the wiring is correct and the workflow simply is not live yet.
- workflowIdstringrequired
- namestringrequired
- triggerstringrequired
- reasonenumrequired
  workflow_pausedworkflow_draft

Errors

Every failure returns the standard envelope — branch on `code`, never on the wording of `error`.

401Missing or invalid API key.
422Request validation failed (code `validation_error`, 422).

Request

curl https://api.volanea.com/v1/events \
  -X POST \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome",
    "email": "ada@example.com",
    "data": {},
    "contact": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "locale": "en",
      "data": {}
    }
  }'

Response

200 · application/json

{
  "success": true,
  "data": {
    "eventId": "<eventId>",
    "contactId": "con_5e90",
    "triggered": [
      {
        "workflowId": "wf_7d31",
        "name": "Welcome",
        "trigger": "<trigger>",
        "status": "dispatched"
      }
    ],
    "skipped": [
      {
        "workflowId": "wf_7d31",
        "name": "Welcome",
        "trigger": "<trigger>",
        "reason": "workflow_paused"
      }
    ]
  }
}

92 endpoints · OpenAPI document