Events › Report an event against a click

Events

Report an event against a click

POST/api/{ORG}/links/{link}/clicks/{click}/events/{name}Permalink

Records what a tracked visit led to, against the click in the brv_click value the destination received (<click id>.<link id>): sale (with amount and currency, a secret key only), install (from an app, its install referrer or clipboard), lead, or any name of your own. Ids in the address win over the body. Answers 201 with the event, or 200 with repeated: true for one it already has.

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/links/01JC6Y8QH2M4ZK7T9VRW3XNB5D/clicks/01JC6Y8QH2M4ZK7T9VRW3XNB5D/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
linkstringrequired—
clickstringrequired—
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.