---
title: "Submit a fingerprint event"
method: POST
path: "/fingerprint/events"
---

# Submit a fingerprint event

`POST /fingerprint/events`

Submits an SDK fingerprint payload and returns a client-scoped device id with curated signals. The OAuth client id is taken from the access token. clientId is not a request field. Safe retries of the same request use the standard Idempotency-Key header.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `fingerprint` string, required — Opaque base64 payload returned by the Stitch SDK.
  - `correlationId` string — Optional business reference for logs and support. Not an idempotency key.
  - `userId` string — Optional merchant user identifier. Not used for matching.
  - `metadata` FingerprintMetadata — Flat key-value object stored with the fingerprint event. Nested objects and arrays are rejected. Serialized JSON must be at most 4096 UTF-8 bytes.

## Response `200`

Fingerprint event resolved.

- FingerprintEvent
  - `id` string, required — Stitch event resource id.
  - `correlationId` string, required — Merchant business reference for this submit.
  - `userId` string — Merchant-supplied user identifier.
  - `deviceId` string, required — Client-scoped device identifier.
  - `metadata` FingerprintMetadata — Flat key-value object stored with the fingerprint event. Nested objects and arrays are rejected. Serialized JSON must be at most 4096 UTF-8 bytes.
  - `signals` FingerprintSignals, required
    - `platform` 'web' | 'ios' | 'android'
    - `ip` object
      - `address` string
      - `country` string
    - `device` object
      - `os` object
        - `name` string
        - `version` string
      - `browser` object
        - `name` string
        - `version` string
      - `userAgent` string
      - `screenResolution` object
        - `width` number, required
        - `height` number, required
      - `timezone` string
      - `languages` string[]
  - `createdAt` string, date-time, required

## Other responses

- `400` — Invalid request body or idempotency key.
- `401` — Missing, expired, or invalid access token.
- `403` — The token lacks the client_fingerprinting scope.
- `409` — Idempotency conflict.
- `500` — Unexpected server failure.

---

[API](https://skmtc.dev/stitch/apis/stitch-api.md) · [All operations](https://skmtc.dev/stitch/apis/stitch-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stitch/stitch-api/revisions/8c5a258567d0/schema)