Events › Report an event against a link
Events
Report an event against a link
POST/api/{ORG}/links/{link}/events/{name}Permalink
Records an event against a link with no click (one is not known): its name as for a click’s, the URL’s link winning over the body. 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
curl -X POST "https://console.brevily.com/api/NORTHWIND/links/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/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 | — | |
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.
Type a call, a field or a guide.