Send a custom event

curl --request POST \
  --url https://e.trackplay.io/v1/event \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event": "quiz_completed",
  "session_id": "3b1e5c90-77aa-4f2d-8c31-6de0a9b41c22",
  "value": 10,
  "event_id": "quiz_10482",
  "properties": {
    "plan": "pro",
    "score": "8"
  }
}
'

{
  "ok": true,
  "event": "quiz_completed",
  "event_id": "quiz_10482",
  "attributed": true,
  "matched_by": "session_id"
}

{
  "ok": true,
  "event": "quiz_completed",
  "event_id": "quiz_10482",
  "attributed": false,
  "matched_by": null
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

POST

event

curl --request POST \
  --url https://e.trackplay.io/v1/event \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event": "quiz_completed",
  "session_id": "3b1e5c90-77aa-4f2d-8c31-6de0a9b41c22",
  "value": 10,
  "event_id": "quiz_10482",
  "properties": {
    "plan": "pro",
    "score": "8"
  }
}
'

{
  "ok": true,
  "event": "quiz_completed",
  "event_id": "quiz_10482",
  "attributed": true,
  "matched_by": "session_id"
}

{
  "ok": true,
  "event": "quiz_completed",
  "event_id": "quiz_10482",
  "attributed": false,
  "matched_by": null
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

A scoped token minted in Settings → API tokens. Send it as Authorization: Bearer tplt_… or X-API-Key: tplt_….

Body

application/json

event

string

required

The event name, e.g. quiz_completed. Lowercased and reduced to [a-z0-9_-], then truncated to 64 characters. A workspace may use 100 distinct names, so keep the set small and fixed.

Maximum string length: 120

Example:

"quiz_completed"

session_id

string

The viewer's session. This is the best identifier to send. Read it from the player with window.trackplay.getSessionId().

Maximum string length: 100

device_id

string

Fallback if you have no session.

Maximum string length: 100

profile_id

string

Fallback if you have no session or device.

Maximum string length: 100

string

Identity fallback. Hashed on arrival and never stored raw.

Maximum string length: 255

external_id

string

Identity fallback. Your own customer ID, if you have already linked it.

Maximum string length: 120

value

number

A number to report on this event. Not revenue. It never feeds revenue, ROAS, EPC, or RPV. Clamped to plus or minus 1,000,000,000.

video_code

string

Credit the event to a specific video. Wins over the session's last video.

Maximum string length: 100

event_id

string

Your idempotency key. Send one. A retry with the same event_id collapses into the same row instead of double counting. Omit it and delivery is at-least-once, so duplicates are possible.

Maximum string length: 120

properties

object

Up to 20 extra key/value pairs. Keys are capped at 40 characters, values at 100. This is where varying data belongs. Never in the event name.

timestamp

string<date-time>

When the event happened. Defaults to arrival time.

Response

Recorded and attributed to a session.

boolean

event

string

The normalized event name that was stored.

event_id

string

Your event_id, or the one generated for you.

attributed

boolean

Whether the event landed on a viewer's session.

matched_by

enum<string> | null

Which identifier resolved the viewer. null when nothing matched.

Available options:

session_id,

device_id,

profile_id,

identity,

null

⌘I

Getting Started

Guides

Endpoints

Authorizations

Body

Response