Track events
curl --request POST \
--url https://apix.spotzee.com/api/client/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
[
{
"name": "product_viewed",
"anonymous_id": "anon-2c8a3e",
"external_id": "cust-9f4b21",
"data": {
"product_id": "sku-1024",
"value": 49.95,
"currency": "AUD"
},
"user": {
"email": "jane@example.com",
"phone": "+61400123456",
"timezone": "Australia/Sydney",
"locale": "en-AU",
"data": {
"plan": "pro"
}
},
"created_at": "2026-04-28T05:14:00.000Z"
}
]
'import requests
url = "https://apix.spotzee.com/api/client/events"
payload = [
{
"name": "product_viewed",
"anonymous_id": "anon-2c8a3e",
"external_id": "cust-9f4b21",
"data": {
"product_id": "sku-1024",
"value": 49.95,
"currency": "AUD"
},
"user": {
"email": "jane@example.com",
"phone": "+61400123456",
"timezone": "Australia/Sydney",
"locale": "en-AU",
"data": { "plan": "pro" }
},
"created_at": "2026-04-28T05:14:00.000Z"
}
]
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify([
{
name: 'product_viewed',
anonymous_id: 'anon-2c8a3e',
external_id: 'cust-9f4b21',
data: {product_id: 'sku-1024', value: 49.95, currency: 'AUD'},
user: {
email: 'jane@example.com',
phone: '+61400123456',
timezone: 'Australia/Sydney',
locale: 'en-AU',
data: {plan: 'pro'}
},
created_at: '2026-04-28T05:14:00.000Z'
}
])
};
fetch('https://apix.spotzee.com/api/client/events', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://apix.spotzee.com/api/client/events"
payload := strings.NewReader("[\n {\n \"name\": \"product_viewed\",\n \"anonymous_id\": \"anon-2c8a3e\",\n \"external_id\": \"cust-9f4b21\",\n \"data\": {\n \"product_id\": \"sku-1024\",\n \"value\": 49.95,\n \"currency\": \"AUD\"\n },\n \"user\": {\n \"email\": \"jane@example.com\",\n \"phone\": \"+61400123456\",\n \"timezone\": \"Australia/Sydney\",\n \"locale\": \"en-AU\",\n \"data\": {\n \"plan\": \"pro\"\n }\n },\n \"created_at\": \"2026-04-28T05:14:00.000Z\"\n }\n]")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}Events
Track events
Records one or more behavioural events against a user. Events drive segmentation and journey triggers. Up to 100 events per request — supplying both anonymous_id and external_id on an event links the two identifiers. Optionally pass a user block to update the user’s profile in the same call.
Idempotent — pass an Idempotency-Key header to make safely retryable. On a replay the original response is returned with Idempotent-Replayed: true. See the API conventions guide for the full state machine, TTL, and mismatch behaviour.
POST
/
events
Track events
curl --request POST \
--url https://apix.spotzee.com/api/client/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
[
{
"name": "product_viewed",
"anonymous_id": "anon-2c8a3e",
"external_id": "cust-9f4b21",
"data": {
"product_id": "sku-1024",
"value": 49.95,
"currency": "AUD"
},
"user": {
"email": "jane@example.com",
"phone": "+61400123456",
"timezone": "Australia/Sydney",
"locale": "en-AU",
"data": {
"plan": "pro"
}
},
"created_at": "2026-04-28T05:14:00.000Z"
}
]
'import requests
url = "https://apix.spotzee.com/api/client/events"
payload = [
{
"name": "product_viewed",
"anonymous_id": "anon-2c8a3e",
"external_id": "cust-9f4b21",
"data": {
"product_id": "sku-1024",
"value": 49.95,
"currency": "AUD"
},
"user": {
"email": "jane@example.com",
"phone": "+61400123456",
"timezone": "Australia/Sydney",
"locale": "en-AU",
"data": { "plan": "pro" }
},
"created_at": "2026-04-28T05:14:00.000Z"
}
]
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify([
{
name: 'product_viewed',
anonymous_id: 'anon-2c8a3e',
external_id: 'cust-9f4b21',
data: {product_id: 'sku-1024', value: 49.95, currency: 'AUD'},
user: {
email: 'jane@example.com',
phone: '+61400123456',
timezone: 'Australia/Sydney',
locale: 'en-AU',
data: {plan: 'pro'}
},
created_at: '2026-04-28T05:14:00.000Z'
}
])
};
fetch('https://apix.spotzee.com/api/client/events', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://apix.spotzee.com/api/client/events"
payload := strings.NewReader("[\n {\n \"name\": \"product_viewed\",\n \"anonymous_id\": \"anon-2c8a3e\",\n \"external_id\": \"cust-9f4b21\",\n \"data\": {\n \"product_id\": \"sku-1024\",\n \"value\": 49.95,\n \"currency\": \"AUD\"\n },\n \"user\": {\n \"email\": \"jane@example.com\",\n \"phone\": \"+61400123456\",\n \"timezone\": \"Australia/Sydney\",\n \"locale\": \"en-AU\",\n \"data\": {\n \"plan\": \"pro\"\n }\n },\n \"created_at\": \"2026-04-28T05:14:00.000Z\"\n }\n]")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}{
"status": "error",
"code": "resource_missing",
"message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
"error": "<string>",
"title": "Resource missing",
"type": "https://docs.spotzee.com/main-api/errors#resource_missing",
"request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
"param": "id",
"errors": [
{
"param": "email",
"code": "parameter_invalid_format",
"message": "Must be a valid email address."
}
]
}Authorizations
projectApiKeypublishableKey
Project-scoped secret API key (sk_…). Pass in the Authorization: Bearer <key> header. Grants access to the project the key was issued for.
Body
application/json
Required array length:
1 - 100 elements- Option 1
- Option 2
A single event payload. At least one of anonymous_id or external_id must be present so the event can be attributed to a user. Supplying both links the two identifiers.
Event name. Stable, machine-readable identifier — used in segments and journey triggers.
Minimum string length:
1Example:
"product_viewed"
Anonymous tracking identifier captured before the user was identified.
Example:
"anon-2c8a3e"
Optional system-of-record identifier — links the event to an identified user.
Example:
"cust-9f4b21"
Free-form event payload. Indexed for use in segments and journey conditions.
Example:
{
"product_id": "sku-1024",
"value": 49.95,
"currency": "AUD"
}
Optional user-profile fields applied alongside the event. Lets a single call both record a behaviour and update the user, avoiding a separate identify request.
Hide child attributes
Hide child attributes
Email address to associate with the user when the event is processed.
Example:
"jane@example.com"
Phone number to associate with the user when the event is processed.
Example:
"+61400123456"
IANA timezone to set on the user (for example Australia/Sydney).
Maximum string length:
50Example:
"Australia/Sydney"
BCP-47 locale tag (for example en-AU).
Maximum string length:
255Example:
"en-AU"
Custom attributes to merge onto the user’s profile.
Example:
{ "plan": "pro" }
Time the event occurred. Defaults to the server-receive time when omitted. ISO 8601.
Example:
"2026-04-28T05:14:00.000Z"
Response
The batch was accepted for asynchronous processing.
Empty response body. Returned with HTTP 204 when an operation is accepted for processing.
Was this page helpful?
⌘I