Bulk upsert users (synchronous)

curl --request POST \
  --url https://apix.spotzee.com/api/client/users/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "anonymous_id": "anon-2c8a3e",
    "external_id": "cust-9f4b21",
    "email": "jane@example.com",
    "phone": "+61400123456",
    "timezone": "Australia/Sydney",
    "locale": "en-AU",
    "data": {
      "first_name": "Jane",
      "plan": "pro"
    }
  }
]
'

import requests

url = "https://apix.spotzee.com/api/client/users/batch"

payload = [
    {
        "anonymous_id": "anon-2c8a3e",
        "external_id": "cust-9f4b21",
        "email": "jane@example.com",
        "phone": "+61400123456",
        "timezone": "Australia/Sydney",
        "locale": "en-AU",
        "data": {
            "first_name": "Jane",
            "plan": "pro"
        }
    }
]
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([
    {
      anonymous_id: 'anon-2c8a3e',
      external_id: 'cust-9f4b21',
      email: 'jane@example.com',
      phone: '+61400123456',
      timezone: 'Australia/Sydney',
      locale: 'en-AU',
      data: {first_name: 'Jane', plan: 'pro'}
    }
  ])
};

fetch('https://apix.spotzee.com/api/client/users/batch', 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/users/batch"

	payload := strings.NewReader("[\n  {\n    \"anonymous_id\": \"anon-2c8a3e\",\n    \"external_id\": \"cust-9f4b21\",\n    \"email\": \"jane@example.com\",\n    \"phone\": \"+61400123456\",\n    \"timezone\": \"Australia/Sydney\",\n    \"locale\": \"en-AU\",\n    \"data\": {\n      \"first_name\": \"Jane\",\n      \"plan\": \"pro\"\n    }\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))

}

{
  "results": [
    {
      "index": 0,
      "external_id": "cust-9f4b21",
      "anonymous_id": "<string>",
      "user": {
        "id": 1024,
        "project_id": 42,
        "external_id": "cust-9f4b21",
        "created_at": "2026-04-28T05:14:00.000Z",
        "updated_at": "2026-04-28T05:14:00.000Z",
        "anonymous_id": "anon-2c8a3e",
        "email": "jane@example.com",
        "phone": "+61400123456",
        "timezone": "Australia/Sydney",
        "locale": "en-AU",
        "data": {
          "first_name": "Jane",
          "last_name": "Doe",
          "plan": "pro"
        },
        "has_push_device": true,
        "devices": [
          {}
        ]
      },
      "error": {
        "code": "resource_missing",
        "message": "User identity could not be resolved."
      }
    }
  ],
  "succeeded": 2,
  "failed": 0
}

{
  "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."
    }
  ]
}

Users

Bulk upsert users (synchronous)

Creates or updates up to 100 users in a single call and reports per-item success or failure before returning. Each input must include either anonymous_id or external_id; supplying both links the two identifiers. Use this when the calling system needs to react to partial failures inline; use PATCH /users instead for fire-and-forget queued processing.

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

users

batch

Bulk upsert users (synchronous)

curl --request POST \
  --url https://apix.spotzee.com/api/client/users/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "anonymous_id": "anon-2c8a3e",
    "external_id": "cust-9f4b21",
    "email": "jane@example.com",
    "phone": "+61400123456",
    "timezone": "Australia/Sydney",
    "locale": "en-AU",
    "data": {
      "first_name": "Jane",
      "plan": "pro"
    }
  }
]
'

import requests

url = "https://apix.spotzee.com/api/client/users/batch"

payload = [
    {
        "anonymous_id": "anon-2c8a3e",
        "external_id": "cust-9f4b21",
        "email": "jane@example.com",
        "phone": "+61400123456",
        "timezone": "Australia/Sydney",
        "locale": "en-AU",
        "data": {
            "first_name": "Jane",
            "plan": "pro"
        }
    }
]
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([
    {
      anonymous_id: 'anon-2c8a3e',
      external_id: 'cust-9f4b21',
      email: 'jane@example.com',
      phone: '+61400123456',
      timezone: 'Australia/Sydney',
      locale: 'en-AU',
      data: {first_name: 'Jane', plan: 'pro'}
    }
  ])
};

fetch('https://apix.spotzee.com/api/client/users/batch', 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/users/batch"

	payload := strings.NewReader("[\n  {\n    \"anonymous_id\": \"anon-2c8a3e\",\n    \"external_id\": \"cust-9f4b21\",\n    \"email\": \"jane@example.com\",\n    \"phone\": \"+61400123456\",\n    \"timezone\": \"Australia/Sydney\",\n    \"locale\": \"en-AU\",\n    \"data\": {\n      \"first_name\": \"Jane\",\n      \"plan\": \"pro\"\n    }\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))

}

{
  "results": [
    {
      "index": 0,
      "external_id": "cust-9f4b21",
      "anonymous_id": "<string>",
      "user": {
        "id": 1024,
        "project_id": 42,
        "external_id": "cust-9f4b21",
        "created_at": "2026-04-28T05:14:00.000Z",
        "updated_at": "2026-04-28T05:14:00.000Z",
        "anonymous_id": "anon-2c8a3e",
        "email": "jane@example.com",
        "phone": "+61400123456",
        "timezone": "Australia/Sydney",
        "locale": "en-AU",
        "data": {
          "first_name": "Jane",
          "last_name": "Doe",
          "plan": "pro"
        },
        "has_push_device": true,
        "devices": [
          {}
        ]
      },
      "error": {
        "code": "resource_missing",
        "message": "User identity could not be resolved."
      }
    }
  ],
  "succeeded": 2,
  "failed": 0
}

{
  "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

Authorization

string

header

required

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 user upsert. At least one of anonymous_id or external_id must be present. When both are present they are linked.

anonymous_id

string

required

Anonymous tracking identifier captured before the user was identified.

Example:

"anon-2c8a3e"

external_id

string | null

Optional system-of-record identifier to attach to this anonymous user.

Example:

"cust-9f4b21"

string<email> | null

User’s email address. Validated against RFC 5322 on write.

Example:

"jane@example.com"

phone

string | null

User’s phone number. E.164 preferred; other formats are normalised when possible.

Example:

"+61400123456"

timezone

string | null

IANA timezone (for example Australia/Sydney).

Maximum string length: 50

Example:

"Australia/Sydney"

locale

string | null

BCP-47 locale tag (for example en-AU).

Maximum string length: 255

Example:

"en-AU"

data

object | null

Free-form custom attributes attached to the user. Used in segmentation and template rendering.

Example:

{ "first_name": "Jane", "plan": "pro" }

Response

Per-item upsert outcomes. Partial success is allowed.

Synchronous result of a bulk user upsert. Partial success is allowed.

results

object[]

required

Per-item outcomes in the same order as the request body.

Hide child attributes

results.index

integer

required

Position of this item in the request body, zero-indexed.

Example:

0

results.external_id

string | null

External identifier supplied by the caller for this user, when available.

Example:

"cust-9f4b21"

results.anonymous_id

string | null

Anonymous identifier supplied by the caller for this user, when available.

results.user

object

The persisted user, present when the item upserted successfully.

Hide child attributes

results.user.id

integer

required

Numeric identifier. Use external_id as the stable cross-system reference.

Example:

1024

results.user.project_id

integer

required

Identifier of the project this user belongs to.

Example:

42

results.user.external_id

string

required

Stable identifier supplied by the calling system. Treated as the user’s primary key for upserts.

Example:

"cust-9f4b21"

results.user.created_at

string | null

required

Time the user was first created. ISO 8601.

Example:

"2026-04-28T05:14:00.000Z"

results.user.updated_at

string | null

required

Time the user was last modified. ISO 8601.

Example:

"2026-04-28T05:14:00.000Z"

results.user.anonymous_id

string | null

Anonymous tracking identifier captured before the user was identified, when available.

Example:

"anon-2c8a3e"

results.user.email

string | null

User’s email address. Format-validated on write.

Example:

"jane@example.com"

results.user.phone

string | null

User’s phone number in E.164 format on read.

Example:

"+61400123456"

results.user.timezone

string | null

IANA timezone used for time-of-day delivery scheduling.

Example:

"Australia/Sydney"

results.user.locale

string | null

BCP-47 locale used for content rendering.

Example:

"en-AU"

results.user.data

object

Free-form custom attributes attached to the user. Used in segmentation and template rendering.

Example:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "plan": "pro"
}

results.user.has_push_device

boolean

True when the user has at least one registered push device.

results.user.devices

object[]

Registered push devices, when included.

results.error

object

Failure detail, present when the item could not be persisted.

Hide child attributes

results.error.code

enum<string>

required

Per-item error code drawn from the canonical 16-code catalogue.

Available options:

resource_missing,

resource_already_exists,

state_conflict,

archived_user_conflict,

user_capacity_exhausted,

parameter_missing,

parameter_invalid_empty,

parameter_invalid_format,

parameter_unknown,

validation_failed,

authentication_required,

permission_denied,

idempotency_key_mismatch,

idempotency_key_invalid,

idempotency_in_progress,

rate_limited,

version_unsupported,

version_required,

webhook_signature_invalid,

quota_exceeded,

service_unavailable,

internal_error

Example:

"resource_missing"

results.error.message

string

required

Human-readable, en-AU explanation of why this item failed.

Example:

"User identity could not be resolved."

succeeded

integer

required

Count of items that upserted successfully.

Example:

2

failed

integer

required

Count of items that failed.

Example:

0

Overview

Projects

Events

Campaigns

Lists

Subscriptions

Journeys

Templates

Users

Tags

API keys

Organisation

Billing recovery

Webhooks

CRM

Source Sync

Form definitions

Form submissions

Bulk upsert users (synchronous)

Authorizations

Body

Response