Skip to content
AzimeaDocs
Dashboard

Track events from your product

POST
/events
curl --request POST \
--url https://api.azimea.com/v1/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "events": [ { "id": "evt_7f3c2a", "name": "user.signed_up", "occurredAt": "2026-10-05T09:30:00+00:00", "contact": { "externalId": "user_123", "email": "emma@example.com" }, "properties": { "plan": "trial", "source": "landing-page" } } ] }'

Tells Azimea what people did in your product (user.signed_up, trial.ending, kyc.completed). Each event is recorded on the person’s timeline and starts every published flow whose trigger is that event name; the person is found, or created, from contact (the same object POST /contacts takes, with at least id, externalId or email). Send up to 100 events per call; a call counts once for the rate limit. id is your own id, unique in your account: sending it again is counted as a duplicate, so retries are safe. Names use lowercase letters, digits, _ and ., start with a letter, at most 64 characters; the prefixes order., cart., customer., subscriber., contact., email. and azimea. are reserved. occurredAt may be up to 30 days in the past and not in the future; properties is a JSON object of at most 16 KB and 3 levels. Each event is accepted or rejected on its own, with activity.* codes per field. Needs the events:write permission.

Media typeapplication/json
object
events
required

The events, up to 100 per call. Each is accepted or rejected on its own.

Array<object>
>= 1 characters
object
id

Your own id for this event, unique in your account. Sending it again counts as a duplicate, so retries are safe.

string
nullable
Example
evt_7f3c2a
name

What happened: lowercase letters, digits, _ and ., starting with a letter, at most 64 characters. The prefixes order., cart., customer., subscriber., contact., email. and azimea. are reserved.

string
nullable
Example
user.signed_up
occurredAt

When it happened: at most 30 days in the past, never in the future. Now, when left out.

string format: date-time
nullable
Example
2026-10-05T09:30:00+00:00
contact

Who did it: the same object POST /contacts takes, with at least a user id (externalId) or an email.

nullable
Example
{
"externalId": "user_123",
"email": "emma@example.com"
}
properties

Anything about the event, as a JSON object of at most 16 KB and 3 levels deep. Flows can filter on it and emails can show it.

nullable
Example
{
"plan": "trial",
"source": "landing-page"
}
Example
[
{
"id": "evt_7f3c2a",
"name": "user.signed_up",
"occurredAt": "2026-10-05T09:30:00+00:00",
"contact": {
"externalId": "user_123",
"email": "emma@example.com"
},
"properties": {
"plan": "trial",
"source": "landing-page"
}
}
]
Example
{
"events": [
{
"id": "evt_7f3c2a",
"name": "user.signed_up",
"occurredAt": "2026-10-05T09:30:00+00:00",
"contact": {
"externalId": "user_123",
"email": "emma@example.com"
},
"properties": {
"plan": "trial",
"source": "landing-page"
}
}
]
}

How many events were accepted, were duplicates, or were rejected (with the reasons per event)

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

object
accepted

How many events were accepted.

integer format: int32
duplicates

How many were ignored because their id was already used.

integer format: int32
rejected

The events that were refused, each with its position and reasons.

Array<object>
object
index

The event’s position in your request, starting at 0.

integer format: int32
errors

Why it was refused.

Array<object>
object
code

A stable error code, listed in the error codes catalog.

string
field

The event field the problem is about.

string
params

The numbers the code refers to (a minimum, a maximum), when there are any.

object
key
additional properties
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Example
{
"isSuccess": true,
"value": {
"accepted": 1,
"duplicates": 0,
"rejected": []
},
"status": 0,
"errors": [],
"fieldErrors": null
}

Validation failed: no events, or more than 100 (activity.batch_too_large)

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

nullable
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Example
{
"isSuccess": false,
"value": null,
"status": 5,
"errors": [
{
"code": "validation.required",
"message": "Fill in this field.",
"params": null
}
],
"fieldErrors": {
"email": [
{
"code": "validation.required",
"message": "Fill in this field.",
"params": null
}
]
}
}

Missing or invalid API key

The key lacks the events:write permission

Too many requests for this key