Events › Report an event

Events

Report an event

POST/api/{ORG}/events/{name}Permalink

Records an event against the organisation: with a customer already reported against a click, against that customer’s first click (first touch); else against no link. Any link or click in the body is ignored: name them in the address. Answers 201 with the event, or 200 with repeated: true.

Permission
Integrations · create
Plan
Plans that include the API: Pricing
Retry
Safe with an Idempotency-Key

Example request

bash
curl -X POST "https://console.brevily.com/api/NORTHWIND/events/general" \  -H "x-api-key: brv_ak_7Fq2Lw9xK3" \  -H "x-api-secret: $BREVILY_SECRET" \  -H "Idempotency-Key: 4f9c1e2a-autumn" \  -H "Content-Type: application/json" \  -d '{    "customer": "example",    "amount": 1,    "currency": "example",    "id": "01JC6Y8QH2M4ZK7T9VRW3XNB5D",    "dedupe": "example",    "occurredAt": "2026-11-05T09:41:00Z",    "properties": "example",    "key": "example"  }'

Example answer

json
{  "id": "01JC6Y8QH2M4ZK7T9VRW3XNB5D",  "link": "example",  "click": "example",  "event": "example",  "source": "SERVER",  "amount": 1,  "currency": "example",  "customer": "example",  "properties": "example",  "occurredAt": "2026-11-05T09:41:00Z",  "repeated": false}

Made-up values. Send your own Idempotency-Key, one per change.

PathPermalink

Path parameters
NameTypeRequiredDescriptionAllowed values
ORGstringrequiredYour organisation’s code.3 to 20 characters
namestringrequired—

BodyPermalink

JSON. An unknown field is refused with a 400 naming it.

Body fields
NameTypeRequiredDescriptionAllowed values
customerstringoptionalYour id for the person (1-128 characters, no spaces): binds them to the click, or finds their first click.—
amountintegeroptionalThe amount in minor units (cents); needs currency. A sale needs both; a publishable key sends none.—
currencystringoptionalThe amount’s ISO 4217 currency; needs amount.—
idstringoptionalYour own id for this event; a repeat of it is recorded once.—
dedupestringoptionalThe same as id (brv.js’s word); id wins when both are sent.—
occurredAtdate-timeoptionalWhen it happened, ISO 8601; now when left out. Not in the future.—
propertiesanyoptionalUp to 15 names of your own, each starting with a letter, then letters, digits or _, at most 40 characters, with a text (at most 100 characters), number or true/false value, 2,048 bytes in all. Never personal data.—
keystringoptionalA publishable key, when it cannot travel in the x-brevily-key header (sendBeacon).—

AnswerPermalink

EventReport

Answer fields
NameTypeDescriptionAllowed values
idstringThe event’s id.—
linkstringThe link it is against; null for one against no link.or null
clickstringThe click it is bound to (the id in brv_click); null for none.or null
eventstringWhat happened: sale, install, lead, or any name you report.—
sourcestringWho reported it: a server with a secret key, an app with its key, or a site with its website key.SERVER, DEVICE, WEB
amountintegerThe amount in minor units (cents); null for none.or null
currencystringThe amount’s ISO 4217 currency; null for none.or null
customerstringYour id for the person; null when not given.or null
propertiesanyIts properties, as reported: names with a text, number or true/false value; {} for none.—
occurredAtdate-timeWhen it happened.—
repeatedbooleanIt was recorded already (the same id, or the same click and event): answered 200, counted once.—

ErrorsPermalink

Errors
Status Code When
400 VALIDATION_FAILED A field, a parameter or the body is wrong; details.fields says which.
400 IDEMPOTENCY_KEY_INVALID The Idempotency-Key is longer than 255 characters.
401 UNAUTHENTICATED No key, a key that does not match, or one expired or revoked.
403 ACCESS_DENIED The key lacks Integrations · create, or the organisation’s plan does not include it.
404 NOT_FOUND No organisation with that code for this key, or no such record in it.
409 CONFLICT
409 IDEMPOTENCY_IN_FLIGHT The first call with this Idempotency-Key is still running.
413 PAYLOAD_TOO_LARGE
415 UNSUPPORTED_MEDIA
422 IDEMPOTENCY_MISMATCH The same Idempotency-Key was sent with a different request.
429 RATE_LIMITED Too many calls: wait Retry-After seconds.

Rate limitsPermalink

Counted with every other call of the organisation, by plan: Pricing. The answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; more on rate limits.