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
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" }'const res = await fetch("https://console.brevily.com/api/NORTHWIND/links/01JC6Y8QH2M4ZK7T9VRW3XNB5D/clicks/01JC6Y8QH2M4ZK7T9VRW3XNB5D/events/general", { method: "POST", headers: { "x-api-key": "brv_ak_7Fq2Lw9xK3", "x-api-secret": process.env.BREVILY_SECRET, "Idempotency-Key": "4f9c1e2a-autumn", "Content-Type": "application/json", }, body: JSON.stringify({ "customer": "example", "amount": 1, "currency": "example", "id": "01JC6Y8QH2M4ZK7T9VRW3XNB5D", "dedupe": "example", "occurredAt": "2026-11-05T09:41:00Z", "properties": "example", "key": "example" }),});const answer = await res.json();Example answer
{ "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}{ "code": "VALIDATION_FAILED", "message": "Check the form. customer: Not a value this field takes.", "details": { "fields": { "customer": "Not a value this field takes." } }, "requestId": "18188559082372202519"}Made-up values. Send your own Idempotency-Key, one per change.
PathPermalink
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
ORG | string | required | Your organisation’s code. | 3 to 20 characters |
link | string | required | — | |
click | string | required | — | |
name | string | required | — |
BodyPermalink
JSON. An unknown field is refused with a 400 naming it.
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
customer | string | optional | Your id for the person (1-128 characters, no spaces): binds them to the click, or finds their first click. | — |
amount | integer | optional | The amount in minor units (cents); needs currency. A sale needs both; a publishable key sends none. | — |
currency | string | optional | The amount’s ISO 4217 currency; needs amount. | — |
id | string | optional | Your own id for this event; a repeat of it is recorded once. | — |
dedupe | string | optional | The same as id (brv.js’s word); id wins when both are sent. | — |
occurredAt | date-time | optional | When it happened, ISO 8601; now when left out. Not in the future. | — |
properties | any | optional | Up 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. | — |
key | string | optional | A publishable key, when it cannot travel in the x-brevily-key header (sendBeacon). | — |
AnswerPermalink
EventReport
| Name | Type | Description | Allowed values |
|---|---|---|---|
id | string | The event’s id. | — |
link | string | The link it is against; null for one against no link. | or null |
click | string | The click it is bound to (the id in brv_click); null for none. | or null |
event | string | What happened: sale, install, lead, or any name you report. | — |
source | string | Who reported it: a server with a secret key, an app with its key, or a site with its website key. | SERVER, DEVICE, WEB |
amount | integer | The amount in minor units (cents); null for none. | or null |
currency | string | The amount’s ISO 4217 currency; null for none. | or null |
customer | string | Your id for the person; null when not given. | or null |
properties | any | Its properties, as reported: names with a text, number or true/false value; {} for none. | — |
occurredAt | date-time | When it happened. | — |
repeated | boolean | It was recorded already (the same id, or the same click and event): answered 200, counted once. | — |
ErrorsPermalink
| 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.