> ## Documentation Index > Fetch the complete documentation index at: https://docs.trackplay.io/llms.txt > Use this file to discover all available pages before exploring further. # Identify a viewer > Resolves or mints a viewer profile from identity signals claimed by the page: a raw or pre-hashed email or phone, your own customer ID, or a session or device ID. No token is required or checked; the endpoint is public, CORS-enabled, and rate-limited per IP instead. Because the caller is unauthenticated, a page-claimed identity is written at the lowest rung of TrackPlay's confidence ladder. A verified lead-form submission or a server-to-server event carrying the same email outranks it and wins on conflict. Send a raw `email` together with `video_code` and TrackPlay also tees a lead into the workspace's lead list for that video, in addition to writing the identity graph edge. Pre-hashed email alone does not: a hash cannot populate a human-readable lead record. Server: `https://e.trackplay.io` ## OpenAPI ````yaml /api-reference/openapi.json post /v1/identify openapi: 3.1.0 info: title: TrackPlay API description: >- Send conversions and events to TrackPlay, and read them back. Authenticated with scoped tokens you mint in the dashboard. version: 1.0.0 servers: - url: https://app.trackplay.io/api/v1 description: App API. Conversions, videos, webhooks. - url: https://e.trackplay.io description: Events API. High-volume event ingest. security: - bearerAuth: [] tags: - name: Videos description: Create, read, update, and delete videos, and read workspace metadata. - name: Video settings description: Save a settings draft, publish it live, and read or restore past deploys. - name: Uploads description: >- Upload a source video file in one request or in resumable chunks, and poll its processing status. - name: Captions and chapters description: >- Manage caption tracks, chapter markers, AI-generated segments, and CTA cards on a video. - name: Playlists description: Group videos into a playlist or course, and manage the videos inside it. - name: Webhooks description: Subscribe a URL to TrackPlay lifecycle events and test deliveries. - name: Zapier description: >- The REST-hook endpoints Zapier calls to connect a workspace and manage triggers. - name: Analytics description: Read play, retention, event, and conversion analytics for a video. - name: Exports description: Queue and download bulk analytics exports. - name: Conversions description: Report a sale or a lead, from your own server or from a browser fallback. - name: Events description: Send a custom event tied to a viewer's session. - name: Identity description: Resolve a viewer's identity from the page, with no token required. paths: /v1/identify: post: tags: - Identity summary: Identify a viewer description: >- Resolves or mints a viewer profile from identity signals claimed by the page: a raw or pre-hashed email or phone, your own customer ID, or a session or device ID. No token is required or checked; the endpoint is public, CORS-enabled, and rate-limited per IP instead. Because the caller is unauthenticated, a page-claimed identity is written at the lowest rung of TrackPlay's confidence ladder. A verified lead-form submission or a server-to-server event carrying the same email outranks it and wins on conflict. Send a raw `email` together with `video_code` and TrackPlay also tees a lead into the workspace's lead list for that video, in addition to writing the identity graph edge. Pre-hashed email alone does not: a hash cannot populate a human-readable lead record. Server: `https://e.trackplay.io` operationId: identify requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IdentifyRequest' examples: email: summary: Identify by raw email, tied to a video value: workspace_code: WS123 video_code: 9f2c1a7e-4d3b-4a11-9e77-0b2c5d8e1f34 session_code: 3b1e5c90-77aa-4f2d-8c31-6de0a9b41c22 email: jane@example.com prehashed: summary: Identify with a client-side hash instead of a raw email value: workspace_code: WS123 email_sha256: >- 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 responses: '200': description: Resolved or minted. content: application/json: schema: $ref: '#/components/schemas/IdentifyResponse' examples: resolved: value: ok: true profile_id: prof_9f2c1a7e4d3b4a11 '400': description: >- `INVALID_PAYLOAD`: a field failed validation, or the body carried a field outside the schema. `IDENTITY_REQUIRED`: none of `email`, `email_sha256`, `email_md5`, `phone`, `phone_sha256`, `phone_md5`, `external_id`, `session_code`, `device_id`, or `device_global_id` were present. A call naming no identity signal cannot be resolved to anyone. content: application/json: schema: $ref: '#/components/schemas/EventError' '429': description: Rate limited. 120 requests per minute per IP by default. content: application/json: schema: $ref: '#/components/schemas/EventError' examples: limited: value: error: Too many requests '503': description: >- `IDENTITY_UNAVAILABLE`: the identity store is temporarily unreachable. This is never a rejection of your payload. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/EventError' security: [] servers: - url: https://e.trackplay.io components: schemas: IdentifyRequest: type: object additionalProperties: false required: - workspace_code properties: workspace_code: type: string maxLength: 100 description: Your workspace's public code. Required. video_code: type: string maxLength: 100 description: >- The video this identity is associated with. Send it along with a raw `email` to also tee a lead into the workspace's lead list. session_code: type: string maxLength: 100 description: The tracker's session ID, if you have one. device_id: type: string maxLength: 100 description: The tracker's local device ID, if you have one. device_global_id: type: string maxLength: 100 email: type: string maxLength: 255 description: >- A raw email address. Hashed on arrival to both SHA-256 and MD5, and never stored raw. email_sha256: type: string pattern: ^[0-9a-f]{64}$ description: >- A pre-hashed email, lowercase hex, if you hash client-side instead of sending it raw. email_md5: type: string pattern: ^[0-9a-f]{32}$ phone: type: string maxLength: 64 description: A raw phone number. Normalized to E.164 and hashed on arrival. phone_sha256: type: string pattern: ^[0-9a-f]{64}$ phone_md5: type: string pattern: ^[0-9a-f]{32}$ external_id: type: string maxLength: 120 description: Your own customer ID, if you already have one for this viewer. page_url: type: string maxLength: 2000 description: >- At least one identity signal is required: `email`, `email_sha256`, `email_md5`, `phone`, `phone_sha256`, `phone_md5`, `external_id`, `session_code`, `device_id`, or `device_global_id`. A payload naming none of them is rejected, because it would mint an identity that nothing can ever resolve back to. Any field not listed here is rejected outright: the schema is closed. IdentifyResponse: type: object properties: ok: type: boolean profile_id: type: - string - 'null' description: >- The resolved or newly minted profile ID. `null` only in the failure paths, never on a 200. EventError: type: object properties: error: type: string description: A stable error code, e.g. `INSUFFICIENT_SCOPE`. message: type: string description: What went wrong, in plain English. securitySchemes: bearerAuth: type: http scheme: bearer description: >- A scoped token minted in **Settings → API tokens**. Send it as `Authorization: Bearer tplt_…` or `X-API-Key: tplt_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.