Record a server event

Record a named goal or identify an existing browser visitor from your server.

POST/api/v1/events

Access: Workspace API key · server only · Permission details

JSON request body

JSON request fields
Field	Type	Description
`site`	`string`	Website ID or domain; required for multiple websites.
`visitor_id`Required	`string`	Read window.attriboo.getVisitorId() in the browser and pass it to your backend. Up to 64 characters.
`type`Required	`string`	Operation. Values: goal, identify.
`name`	`string`	Required for goal; up to 120 characters.
`email`	`string`	Required for identify; normalized to lowercase.
`path`	`string`	Page path; up to 500 characters. Default: `/`.
`metadata`	`object`	Optional event properties.

Request examples

Examples run from your server or terminal. Configure ATTRIBOO_TOKEN privately for authenticated requests. Replace example website IDs and values with your own. The examples make real requests when you run them.

cURL request

curl -X POST "https://www.attriboo.com/api/v1/events" \
  -H "Authorization: Bearer $ATTRIBOO_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "site": "site_example",
  "visitor_id": "v_example",
  "type": "goal",
  "name": "Started trial",
  "path": "/signup",
  "metadata": {
    "plan": "pro"
  }
}'

Response

Illustrative response. Fields below are inside the data object. Optional coverage, notes and continuation fields vary by report.

Response fields
Field	Type	Description
`recorded`	`boolean`	Request accepted by ingestion.
`site`	`string`	Website ID.
`type`	`string`	Submitted goal or identify type.
`name`	`string \| null`	Goal name or null.

JSON response

{
  "status": "success",
  "data": {
    "recorded": true,
    "site": "site_example",
    "type": "goal",
    "name": "Started trial"
  }
}

Identify the same visitor

cURL request

curl -X POST "https://www.attriboo.com/api/v1/events" \
  -H "Authorization: Bearer $ATTRIBOO_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "site": "site_example",
  "visitor_id": "v_example",
  "type": "identify",
  "email": "buyer@example.com"
}'

JSON response

{
  "status": "success",
  "data": {
    "recorded": true,
    "site": "site_example",
    "type": "identify",
    "name": null
  }
}

Behavior and limits

Use a workspace key on your backend. Current OAuth grants do not include data:write.

Goals count toward the event allowance; identify calls do not. Saved exclusions and collection controls still apply. An accepted response does not override those controls.

There is no general idempotency-key parameter. Retrying a goal request can add another completion.

Errors and retries OpenAPI JSON