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, such as purchase confirmations, server-authoritative game events, or login handlers.

The Immutable REST API sends events to the Immutable attribution pipeline over HTTP. It uses the same event schemas as the Tracking Pixel and Web SDK. Because events originate from your server, they are authoritative and cannot be dropped by ad blockers or manipulated client-side, making the REST API the recommended source for purchase confirmations and other high-value events. 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.

Deleting User Data

To handle a GDPR Right to Erasure request, call this endpoint from your backend with the user’s anonymousId or userId, not both.

# By anonymous ID
curl -X DELETE "https://api.immutable.com/v1/audience/data?anonymousId=anon-device-abc123" \
  -H "x-immutable-publishable-key: YOUR_PUBLISHABLE_KEY"

# By user ID
curl -X DELETE "https://api.immutable.com/v1/audience/data?userId=user-123" \
  -H "x-immutable-publishable-key: YOUR_PUBLISHABLE_KEY"

Response: 202 Accepted

Field	Where	Required	Description
`x-immutable-publishable-key`	Header	Yes	Your publishable key
`anonymousId`	Query string	One of	The anonymous device or session ID to erase
`userId`	Query string	One of	The canonical user ID to erase

Deletion is processed asynchronously. All tracking data and consent records associated with the identity, including any linked identities, are removed or anonymised across all storage layers.

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

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

Associates a user ID with their activity and 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 account IDs that belong to the same player. Use when a player connects a second account with a different provider, for example a Steam ID linked to a Passport account.Also required: fromId, toId (must be different). from is the account being linked. to is the player’s canonical account.

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

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

Attribution

How tracking data powers player attribution and Hub reports

Data Dictionary

Full reference of event schemas and consent levels

Tracking Pixel

Passive tracking snippet for marketing sites and landing pages

Web SDK

Typed SDK for web games, marketing sites, and SPAs

Unity SDK

In-game tracking for Unity desktop builds

API Keys

Manage your publishable and secret keys

PRODUCTS

GUIDES

When to Use the REST API

What You Need

Quick Start

Authentication

Deleting User Data

API Reference

Endpoints

Sending Events

Message Schema

Event Types

Error Responses

Next Steps

Attribution

Data Dictionary

Tracking Pixel

Web SDK

Unity SDK

API Keys

PRODUCTS

GUIDES

Documentation Index

​When to Use the REST API

​What You Need

​Quick Start

​Authentication

​Consent

​Recording Consent

​Reading Consent

​Deleting User Data

​API Reference

​Endpoints

​Sending Events

​Message Schema

​Event Types

​Error Responses

​Next Steps

Attribution

Data Dictionary

Tracking Pixel

Web SDK

Unity SDK

API Keys

When to Use the REST API

What You Need

Quick Start

Authentication

Consent

Recording Consent

Reading Consent

Deleting User Data

API Reference

Endpoints

Sending Events

Message Schema

Event Types

Error Responses

Next Steps