REST API

The REST API is currently in alpha. APIs and behavior may change between releases.

Who is this for? Backend engineers and game server developers who need to send events from server-side code — purchase confirmations, server-authoritative game events, or login handlers.

The Immutable REST API sends events to the Audience pipeline over HTTP. It uses the same event schemas as the Tracking Pixel and Web SDK — send a JSON payload with the event type, name, and properties, and it flows into the same pipeline as all other surfaces.

When to Use the REST API

You want to…	Use this
Passively capture page views and clicks on a marketing site	Tracking Pixel
Instrument a web app with typed, explicit events	Web SDK
Send events from your game server, backend, or webhook handler	REST API
Send purchase confirmations or server-verified identity events	REST API

What You Need

An Immutable Hub account with a project (get started here)
A publishable key from your project settings (API keys guide)

Quick Start

curl -X POST https://api.immutable.com/v1/audience/messages \
  -H "Content-Type: application/json" \
  -H "x-immutable-publishable-key: YOUR_PUBLISHABLE_KEY" \
  -d '{
    "messages": [{
      "type": "track",
      "messageId": "550e8400-e29b-41d4-a716-446655440000",
      "eventTimestamp": "2026-04-08T12:00:00Z",
      "eventName": "purchase",
      "userId": "user-123",
      "surface": "web",
      "properties": {
        "currency": "USD",
        "value": 9.99,
        "itemId": "sword_01"
      },
      "context": {
        "library": "my-studio-backend",
        "libraryVersion": "1.0.0"
      }
    }]
  }'

Response:

{
  "success": true,
  "accepted": 1,
  "rejected": 0
}

Authentication

All requests require a publishable key in the x-immutable-publishable-key header. Manage your keys in Immutable Hub — see the API Keys guide for how to create one.

Environment	Base URL	Key prefix
Sandbox	`https://api.sandbox.immutable.com`	`pk_imapik-test-`
Production	`https://api.immutable.com`	`pk_imapik-`

You are responsible for obtaining and recording user consent before sending tracking events. The REST API does not enforce consent on your behalf — only send what the user has consented to. The same three-tier model (none / anonymous / full) applies as with the Tracking Pixel and Web SDK. See the Data Dictionary → Consent Model for what each level allows. In brief: at none send nothing; at anonymous omit userId and PII; at full send everything. Call this when a user accepts or declines tracking:

curl -X PUT https://api.immutable.com/v1/audience/tracking-consent \
  -H "Content-Type: application/json" \
  -H "x-immutable-publishable-key: YOUR_PUBLISHABLE_KEY" \
  -d '{
    "anonymousId": "anon-device-abc123",
    "status": "full",
    "source": "cookie-banner-v1"
  }'

Response: 204 No Content

Field	Type	Required	Description
`anonymousId`	string	Yes	The anonymous ID used in your events. Max 256 chars.
`status`	string	Yes	`none`, `anonymous`, or `full`
`source`	string	Yes	Where the consent decision originated (e.g. `cookie-banner-v1`). Max 128 chars.

Retrieve a stored consent preference at session start:

curl "https://api.immutable.com/v1/audience/tracking-consent?anonymousId=anon-device-abc123" \
  -H "x-immutable-publishable-key: YOUR_PUBLISHABLE_KEY"

{ "status": "full" }

If no consent has been recorded, the response is { "status": "not_set" }. Treat not_set the same as none.

API Reference

Endpoints

Method	Path	Purpose
POST	`/v1/audience/messages`	Ingest up to 100 events per request
GET	`/v1/audience/tracking-consent?anonymousId=`	Read stored consent status
PUT	`/v1/audience/tracking-consent`	Record a consent decision
DELETE	`/v1/audience/data?anonymousId=` or `?userId=`	GDPR erasure request — coming soon

Sending Events

Headers:

Header	Required	Value
`Content-Type`	Yes	`application/json`
`x-immutable-publishable-key`	Yes	Your publishable key

Response:

{
  "success": true,
  "accepted": 2,
  "rejected": 0
}

The endpoint returns 200 OK even if some messages fail validation — invalid messages are silently skipped. Check the rejected count to detect failures. A 400 means the entire request failed (invalid key or malformed body).

Message Schema

Field	Type	Required	Description
`type`	string	Yes	`track`, `identify`, `alias`, `page`, or `screen`
`messageId`	string (UUID)	Yes	Unique per message — used for deduplication
`eventTimestamp`	string (ISO 8601)	Yes	When the event occurred, not when you send it. Must include a timezone offset (e.g. `2026-04-08T12:00:00Z`). Up to 30 days in the past accepted.
`context`	object	Yes	Must include `library` (your system name) and `libraryVersion`
`userId`	string	—	Your canonical user ID. Required on most types unless `anonymousId` is set.
`anonymousId`	string	—	Anonymous device or session ID. Required if `userId` is absent.
`surface`	string	—	`web`, `pixel`, `unity`, or `unreal`

Most string fields accept up to 256 characters. pageUrl, pagePath, and pageReferrer accept up to 2048.

Optional fields inside the context object

Use these to pass environment metadata alongside the required library and libraryVersion. Include whichever are relevant — all are optional.

Field	Description
`userAgent`	Browser or client user agent
`browserLanguage`	Browser language from `navigator.language` (e.g. `en-US`)
`locale`	App or game locale setting (e.g. `en-US`)
`timezone`	e.g. `America/New_York`
`screen`	Screen resolution (e.g. `1920x1080`)
`pageUrl`	Full page URL
`pagePath`	URL path only
`pageReferrer`	Referrer URL
`pageTitle`	Page title

"context": {
  "library": "my-studio-backend",
  "libraryVersion": "1.0.0",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "timezone": "America/New_York",
  "pageUrl": "https://mygame.com/shop",
  "pageTitle": "Shop"
}

Event Types

track

Record a named event. The most common message type.Also required: eventName, plus userId or anonymousId

{
  "type": "track",
  "messageId": "550e8400-e29b-41d4-a716-446655440001",
  "eventTimestamp": "2026-04-08T12:00:00Z",
  "eventName": "purchase",
  "userId": "user-123",
  "surface": "web",
  "properties": { "currency": "USD", "value": 9.99, "itemId": "sword_01" },
  "context": { "library": "my-studio-backend", "libraryVersion": "1.0.0" }
}

Use any eventName. Predefined events have defined property schemas — see the Data Dictionary for the full list. Custom event names are also supported.

identify

Associate a user ID with traits. Send when a user logs in, creates an account, or updates their profile.Also required: userId or anonymousId

{
  "type": "identify",
  "messageId": "550e8400-e29b-41d4-a716-446655440004",
  "eventTimestamp": "2026-04-08T12:00:00Z",
  "userId": "user-123",
  "identityType": "passport",
  "traits": { "name": "Player One", "email": "player@example.com" },
  "context": { "library": "my-studio-backend", "libraryVersion": "1.0.0" }
}

identityType values: passport, steam, epic, google, apple, discord, email, custom

alias

Link two identities together — for example, connecting an anonymous visitor to a known user, or linking a Steam ID to a Passport user ID.Also required: fromId, toId (must be different). from is the external or anonymous ID; to is the canonical user ID.

{
  "type": "alias",
  "messageId": "550e8400-e29b-41d4-a716-446655440005",
  "eventTimestamp": "2026-04-08T12:00:00Z",
  "fromId": "76561198000000001",
  "fromType": "steam",
  "toId": "user-123",
  "toType": "passport",
  "context": { "library": "my-studio-backend", "libraryVersion": "1.0.0" }
}

When linking accounts, send alias and identify together in the same batch request.

page

Record a page view. Useful for server-side rendering where you capture page loads on the server.Also required: userId or anonymousId

{
  "type": "page",
  "messageId": "550e8400-e29b-41d4-a716-446655440006",
  "eventTimestamp": "2026-04-08T12:00:00Z",
  "userId": "user-123",
  "properties": { "section": "shop" },
  "context": {
    "library": "my-studio-backend",
    "libraryVersion": "1.0.0",
    "pageUrl": "https://mygame.com/shop",
    "pageTitle": "Shop"
  }
}

screen

Record a screen view in a game client or app. Same schema as page.

{
  "type": "screen",
  "messageId": "550e8400-e29b-41d4-a716-446655440007",
  "eventTimestamp": "2026-04-08T12:00:00Z",
  "userId": "user-123",
  "properties": { "screenName": "main-menu" },
  "context": { "library": "my-game-server", "libraryVersion": "1.2.3" }
}

For predefined event names and their property schemas (purchase, progression, resource, sign_up, and more), see the Data Dictionary.

Error Responses

Status	Meaning
`200`	Request accepted. Check `accepted` and `rejected` counts.
`400`	Malformed request body or key format invalid.
`401`	Publishable key not recognised — check your key is correct.
`500`	Server error — retry with exponential back-off.

Next Steps

Data Dictionary

Predefined event schemas and property definitions

Attribution

How tracking data powers player attribution

Tracking Pixel

Lightweight snippet for marketing sites

Web SDK

Typed SDK for web apps and games

PRODUCTS

GUIDES

When to Use the REST API

What You Need

Quick Start

Authentication

API Reference

Endpoints

Sending Events

Message Schema

Event Types

Error Responses

Next Steps

Data Dictionary

Attribution

Tracking Pixel

Web SDK

PRODUCTS

GUIDES

​When to Use the REST API

​What You Need

​Quick Start

​Authentication

​Consent

​Recording Consent

​Reading Consent

​API Reference

​Endpoints

​Sending Events

​Message Schema

​Event Types

​Error Responses

​Next Steps

Data Dictionary

Attribution

Tracking Pixel

Web SDK

When to Use the REST API

What You Need

Quick Start

Authentication

Consent

Recording Consent

Reading Consent

API Reference

Endpoints

Sending Events

Message Schema

Event Types

Error Responses

Next Steps