Events that start flows

An event is something a person did in your product: signed up, finished onboarding, started a trial, upgraded. Send it to Azimea, and every published flow that starts on that event name starts for that person. This is how onboarding series, activation nudges and trial reminders work without any scheduling code on your side.

Calls use https://dashboard.azimea.com/api/v1 and an API key with the events:write permission.

Send an event

POST /events takes up to 100 events per call.

curl https://dashboard.azimea.com/api/v1/events \
  -H "Authorization: Bearer $AZIMEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "id": "evt_7f3c2a",
      "name": "user.signed_up",
      "occurredAt": "2026-10-05T09:30:00Z",
      "contact": { "externalId": "user_123", "email": "ana@example.com" },
      "properties": { "plan": "trial", "source": "landing-page" }
    }]
  }'

var response = await http.PostAsJsonAsync("events", new
{
    events = new[]
    {
        new
        {
            id = "evt_7f3c2a",
            name = "user.signed_up",
            occurredAt = DateTimeOffset.UtcNow,
            contact = new { externalId = "user_123", email = "ana@example.com" },
            properties = new { plan = "trial", source = "landing-page" }
        }
    }
});

await fetch('https://dashboard.azimea.com/api/v1/events', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.AZIMEA_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    events: [{
      id: 'evt_7f3c2a',
      name: 'user.signed_up',
      occurredAt: new Date().toISOString(),
      contact: { externalId: 'user_123', email: 'ana@example.com' },
      properties: { plan: 'trial', source: 'landing-page' },
    }],
  }),
});

$ch = curl_init('https://dashboard.azimea.com/api/v1/events');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AZIMEA_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['events' => [[
        'id' => 'evt_7f3c2a',
        'name' => 'user.signed_up',
        'occurredAt' => gmdate('c'),
        'contact' => ['externalId' => 'user_123', 'email' => 'ana@example.com'],
        'properties' => ['plan' => 'trial', 'source' => 'landing-page'],
    ]]]),
]);
$result = json_decode(curl_exec($ch), true);

from datetime import datetime, timezone
requests.post(
    "https://dashboard.azimea.com/api/v1/events",
    headers={"Authorization": f"Bearer {os.environ['AZIMEA_API_KEY']}"},
    json={"events": [{
        "id": "evt_7f3c2a",
        "name": "user.signed_up",
        "occurredAt": datetime.now(timezone.utc).isoformat(),
        "contact": {"externalId": "user_123", "email": "ana@example.com"},
        "properties": {"plan": "trial", "source": "landing-page"},
    }]},
)

The answer says how many events were accepted, how many were duplicates, and which were rejected, each with its position in the call and the reasons (code, field). Each event is accepted or rejected on its own.

The event

Field	Rules
`id`	Your own id for this event, unique in your account. Sending it again counts as a duplicate, so retries are safe.
`name`	Lowercase letters, digits, `_` and `.`, starting with a letter, at most 64 characters. The prefixes `order.`, `cart.`, `customer.`, `subscriber.`, `contact.`, `email.` and `azimea.` are reserved for Azimea’s own events.
`occurredAt`	When it happened: at most 30 days in the past, never in the future.
`contact`	Who did it: the same object `POST /contacts` takes, with at least `id`, `externalId` or `email` (`activity.event_contact_required`). The person is found or created from it, and the fields you send (name, attributes, consent) update them.
`properties`	Anything about the event, as a JSON object of at most 16 KB and 3 levels deep. Flows can filter on them and emails can show them.

The checks above happen in the call itself. Finding or creating the person happens a moment later, in the background; if that fails (for example a new person with no email), the event shows as failed in Settings › Events, under Recent events, with the reason.

Which names to use

Any name works. If you use the suggested product events (user.signed_up, user.activated, trial.ending, subscription.started), the ready-made product flows work without changes. Settings › Events lists every event name your account has received, with its properties and how many arrived in the last 30 days.

Start a flow from an event

In Flows, create a new flow and choose An event as its trigger.
Pick the event name. Names already received are suggested; you can also type one your product has not sent yet.
Optional: Only when narrows it to events whose properties match (for example plan equals pro). Leave it empty to start for every one of these events. Filters on properties appear once the event has been received with some.
Add the steps (waits, conditions, emails) and Publish. From then on, every matching event starts the flow for the person who did it.

A person already in this flow (a run still going) is not started a second time by another event; the next event after their run ends starts a new one.

Stop when…

A flow can end early when the person does something else: Stop the workflow when… takes up to 10 events, each with an optional filter. For example: an activation series stops on user.activated, trial reminders stop on subscription.started. The run ends wherever it is, and its history says so.

Use the event in the email

An email in the flow can show what the event said: {{event.plan}} is replaced by the plan property of the event that started the run. Text, numbers and true/false are shown as sent; lists and nested objects are not. The email step lists the placeholders it can use once the event has been received.

Recipes

Activation nudge. Trigger user.signed_up, stop when user.activated. Wait a day, send a tip; wait two more days, send another. People who activate on their own never get the nudges.

Trial ending. Trigger trial.ending (send it a few days before the end), stop when subscription.started. One email with what they lose and how to keep it.

Plan upgrade thank-you. Trigger subscription.started with Only when plan equals pro, then an email that says {{event.plan}}.

Start one flow from outside, with its own token

For a script, Zapier or n8n that should start one specific flow without a general API key, a flow can have an API trigger:

Create the flow with API as its trigger. Its editor shows the Trigger URL.
Press Generate a token. Copy it at once: it is shown only once (it starts with azm_wf_). Generate a new token later replaces it, and the old one stops working at that moment.
Publish the flow, then call the URL:

curl -X POST "$TRIGGER_URL" \
  -H "Authorization: Bearer azm_wf_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "order-10234-review",
    "email": "ana@example.com",
    "firstName": "Ana",
    "externalId": "user_123",
    "attributes": { "plan": "pro" },
    "properties": { "orderNumber": "10234" }
  }'

Only email or externalId is required. The person is found or created as POST /contacts does it; attributes update them.
consent takes the same object as the contacts API. Left out, the person is treated as your customer: whoever holds the token vouches for them.
properties are what this call is about; conditions and emails read them as event.*, with the same limits as an event’s properties.
id (1–100 characters) is your id for this call: the same id twice starts the flow once.
The answer is the person’s contactId and duplicate (whether this id was already used).
Errors: 401 automation.api_trigger_invalid (wrong token), automation.workflow_not_published, automation.trigger_call_id_invalid, automation.trigger_properties_invalid.

Use the API trigger for one flow and one job; use POST /events with an API key when your product reports what people do and several flows may react.