# FacePing API reference

> Every customer endpoint, generated from the API itself.

Source: https://docs.faceping.ai/reference/ (interactive) · Machine-readable: https://docs.faceping.ai/openapi.json

Base URL: https://api-eu.faceping.ai (EU region)

Authenticate with your key in the `X-Api-Key` header, server-side only: a sandbox key (`fp_test_`) works on one practice list, an API key (`fp_…`) comes with going live. Send JSON with `Content-Type: application/json`. Errors: https://docs.faceping.ai/errors.md

## Devices

### Check a device token

`GET /v1/device` (operationId `checkDeviceToken`)

Send a device token (fpd_) in the X-Device-Token header to see which list it's for, how many people a device would download, and when it expires, before you put it in an app. It doesn't download any face data and doesn't count as a sync (lastSyncAt is the device's last real sync). 401 when the token is mistyped or revoked, or its list has been deleted; the message says which.

Responses:

- `200` OK: [DeviceStatus](#devicestatus)
- `401` Missing, mistyped or revoked device token, or its list has been deleted. The message says which, except that a deleted list's token looks the same as a mistyped one: once a list is deleted, so are its tokens.
- `404` The token's list has passed its deletion date, so a device has nothing to download.
- `429` Too many requests: wait and retry.

### Add a check-in device

`POST /v1/lists/{listId}/devices` (operationId `addDevice`)

Returns a read-only, one-list device token for the FacePing SDK on the check-in device (shown once; only its prefix is kept). The response's id is the deviceId. label is optional (up to 100 characters; anything longer is cut). For a list with an end date it expires when the list's faces are deleted; for an ongoing list expiresAt is null and it lasts until you revoke it or delete the list. 404 once a list with an end date is past its deletion date. Never put an API key on a check-in device.

Parameters:

- `listId` (path): string (uuid), required

Request body: [AddDeviceRequest](#adddevicerequest) or null

Responses:

- `201` Created: [AddDeviceResponse](#adddeviceresponse)
- `404` Not Found
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.
- `415` The body wasn't sent as JSON: add Content-Type: application/json.

### List a list's check-in devices

`GET /v1/lists/{listId}/devices` (operationId `listDevices`)

Newest first, including revoked ones (revokedAt). lastSyncAt is when the device last downloaded the list. Tokens themselves are never returned again.

Parameters:

- `listId` (path): string (uuid), required

Responses:

- `200` OK: array of [Device](#device)
- `404` Not Found
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

### Revoke a check-in device

`DELETE /v1/lists/{listId}/devices/{deviceId}` (operationId `revokeDevice`)

The device wipes its face data at its next sync (within minutes when online; offline devices stop verifying within 24 hours).

Parameters:

- `listId` (path): string (uuid), required
- `deviceId` (path): string (uuid), required

Responses:

- `204` No Content
- `404` Not Found
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

## Check-in lists

### Create a check-in list

`POST /v1/lists` (operationId `createList`)

A check-in list is any group of people who check in with their face: a show, a festival, a gym's members, this month's staff list. name (up to 200 characters) is required. It either has an end date or is ongoing. With an end date (endsAt): retentionDays (0 to 30, default your account default, 7 unless changed) decides how long after the list ends every face is deleted, on the server and every device. Ongoing (no endsAt, for members, staff or visitors): maxAgeMonths (1 to 36, required) is how long each person's face is kept after they enrol; it is then deleted (logged as MaxAgeReached) and the person can simply enrol again. Send one or the other, not both. startsAt is optional (defaults to now). Every list must offer a way in without a face check (alternativeEntryAvailable: true). matchMode defaults to your account default (Verify, 1:1 verification, unless changed in Settings). country (optional) is where people check in, as a 2-letter ISO 3166-1 code such as GB, IE, FR or US: it decides the consent wording people see (US: the US biometric data release; EU and EEA countries: the EU wording; anywhere else, the UK included: the UK wording). Without it, the list follows your account's country. The response's consentVersion is the wording that applies. Returns 402 when your plan doesn't allow another list. With a sandbox key: one practice list at a time (409 for a second), Verify only, up to 25 people, each face deleted 24 hours after enrolment, nothing billed.

Request body: [CreateListRequest](#createlistrequest)

Responses:

- `201` Created: [CheckInList](#checkinlist)
- `400` Bad Request: [ProblemMessage](#problemmessage)
- `402` Payment Required: [ProblemMessage](#problemmessage)
- `409` Conflict: [ProblemMessage](#problemmessage)
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.
- `415` The body wasn't sent as JSON: add Content-Type: application/json.

### List your check-in lists

`GET /v1/lists` (operationId `listLists`)

Every list on your account, oldest start first, each with how many people are enrolled (peopleEnrolled) and consentVersion.

Responses:

- `200` OK: array of [CheckInList](#checkinlist)
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

### Get a check-in list

`GET /v1/lists/{listId}` (operationId `getList`)

Includes peopleEnrolled (how many people are enrolled now), enrollmentClosed, country (null when not set) and consentVersion: the consent wording people see for this list (for example uk-v1, eu-v1 or us-v1). Send consentVersion with any consent you collect yourself. endsAt, retentionDays and deleteAfter are null for an ongoing list; maxAgeMonths is null for a list with an end date.

Parameters:

- `listId` (path): string (uuid), required

Responses:

- `200` OK: [CheckInList](#checkinlist)
- `404` Not Found
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

### Rename a list or change its country

`PATCH /v1/lists/{listId}` (operationId `updateList`)

Until anyone enrols. name: up to 200 characters; people see it in the consent wording. country: where people check in, as a 2-letter ISO 3166-1 code (GB, IE, FR, US and so on), or an empty string to clear it so the list follows your account's country. It decides the consent wording people see: US gets the US biometric data release, EU and EEA countries the EU wording, anywhere else (the UK included) the UK wording. Omitted or null leaves it as it is. Any other field is refused with 400: only the name and country can change. Returns 409 once anyone has enrolled, or after enrolment has closed: everyone on a list agrees to the same wording.

Parameters:

- `listId` (path): string (uuid), required

Request body: [UpdateListRequest](#updatelistrequest)

Responses:

- `200` OK: [CheckInList](#checkinlist)
- `400` Bad Request: [ProblemMessage](#problemmessage)
- `404` Not Found
- `409` Conflict: [ProblemMessage](#problemmessage)
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.
- `415` The body wasn't sent as JSON: add Content-Type: application/json.

### Delete a list and all its face data now

`DELETE /v1/lists/{listId}` (operationId `deleteList`)

Irreversible. Recorded in your deletion log (what, when and why, never who). Check-in devices wipe their copy at their next sync.

Parameters:

- `listId` (path): string (uuid), required

Responses:

- `204` No Content
- `404` Not Found
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

## People

### Enrol a person from your server

`POST /v1/lists/{listId}/people` (operationId `enrollPerson`)

For when you collect the photo and consent yourself. personId is your ID for the person (a ticket number or membership number, up to 200 characters). consent.consentVersion must be the list's consentVersion. Consent is checked before the photo is even decoded. The photo (a JPEG or PNG, base64) is used once to make a face template and never stored. Enrolling the same personId again replaces their face (still one person on your bill) and, on an ongoing list, restarts their maximum age; it returns 201 either way. The response's deleteAfter is when this person's face will be deleted. Most integrations use the widget instead (createEnrollmentLink).

Parameters:

- `listId` (path): string (uuid), required

Request body: [EnrollPersonRequest](#enrollpersonrequest)

Responses:

- `201` Created: [EnrollPersonResponse](#enrollpersonresponse)
- `400` Bad Request: [ProblemMessage](#problemmessage)
- `402` Payment Required: [ProblemMessage](#problemmessage)
- `404` Not Found
- `409` Conflict: [ProblemMessage](#problemmessage)
- `413` Payload Too Large
- `422` Unprocessable Entity: [ProblemMessage](#problemmessage)
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.
- `415` The body wasn't sent as JSON: add Content-Type: application/json.

### List enrolled people

`GET /v1/lists/{listId}/people` (operationId `listPeople`)

Newest first, 100 per page (page, from 1). search matches part of a personId. No face data is returned. deleteAfter is when each person's face will be deleted.

Parameters:

- `listId` (path): string (uuid), required
- `search` (query): string
- `page` (query): integer (int32)

Responses:

- `200` OK: [PeoplePage](#peoplepage)
- `404` Not Found
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

### Close enrolment for a list

`POST /v1/lists/{listId}/close-enrollment` (operationId `closeEnrollment`)

No more people can be enrolled (from your server, the widget or the dashboard) and no more enrolment links can be created; devices get the final list at their next sync. Enrolled people stay until their faces are deleted as usual. It can't be reopened. Calling it again changes nothing.

Parameters:

- `listId` (path): string (uuid), required

Responses:

- `200` OK: [CheckInList](#checkinlist)
- `404` Not Found
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

### Look up one person

`GET /v1/lists/{listId}/people/{personId}` (operationId `getPerson`)

Whether someone is enrolled, when, how, under which consent wording, and when their face will be deleted. No face data is returned. URL-encode the personId. 404 when no one with that personId is enrolled.

Parameters:

- `listId` (path): string (uuid), required
- `personId` (path): string, required

Responses:

- `200` OK: [Person](#person)
- `404` Not Found: [ProblemMessage](#problemmessage)
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

### Remove a person and their face data

`DELETE /v1/lists/{listId}/people/{personId}` (operationId `removePerson`)

For withdrawn consent, an erasure request or someone leaving (a member, a member of staff). Takes effect at once; check-in devices drop the face at their next sync. Logged in your deletion log without the personId. URL-encode the personId. 404 when no one with that personId is enrolled.

Parameters:

- `listId` (path): string (uuid), required
- `personId` (path): string, required

Responses:

- `204` No Content
- `404` Not Found
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

### Get a list's consent wording

`GET /v1/lists/{listId}/consent` (operationId `getConsentWording`)

The exact wording people see for this list, with your organisation name, the list's name and its deletion rule filled in. Show it when you collect consent yourself (on your own page or at a front desk), then send consentVersion with the enrolment. consent is the statement the person ticks (for us-v1, the written biometric data release); noticeConfirmation is the second tick, that they've read your privacy notice (privacyUrl); guardian is what a parent or guardian agrees to for someone under 16. 409 until the list has an organisation name and privacy notice link.

Parameters:

- `listId` (path): string (uuid), required

Responses:

- `200` OK: [ListConsentWording](#listconsentwording)
- `404` Not Found: [ProblemMessage](#problemmessage)
- `409` Conflict: [ProblemMessage](#problemmessage)
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

## Check results

### Verify a signed check result

`POST /v1/check-results/verify` (operationId `verifyCheckResult`)

For a backend that needs proof a check really happened (check-ins, access, payments): a check-in device signs every verify outcome with its own key, and the app sends the result's signedResult to your server, which sends it here. FacePing checks the signature against the key the device registered at its first sync, that the device is on one of your lists (a sandbox key: your practice list), that nonce matches when you send one (give the app a fresh nonce for each check), that the result was signed less than 30 days ago and not in the future, and that it hasn't been verified before (each result verifies once: 409 replayed after that). 200 says what the device found: match is true only for a match; outcome has the detail. 422 when it doesn't verify, with reason: malformed (not a FacePing check result), badSignature (altered or not signed by the device's key), unknownKey (signed by another key, usually after the app was reinstalled: add the device again), unknownDevice, wrongAccount, nonceMismatch, tooOld or future. Results can wait in an offline queue: they verify until 30 days old.

Request body: [VerifyCheckResultRequest](#verifycheckresultrequest)

Responses:

- `200` OK: [VerifiedCheckResult](#verifiedcheckresult)
- `409` Conflict: [CheckResultProblem](#checkresultproblem)
- `422` Unprocessable Entity: [CheckResultProblem](#checkresultproblem)
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.
- `415` The body wasn't sent as JSON: add Content-Type: application/json.

## Widget

### Create an enrolment link (for the widget or to send)

`POST /v1/lists/{listId}/enrollment-links` (operationId `createEnrollmentLink`)

Single use, for one person: personId is your ID for them (a ticket number or membership number). Pass the token to the widget (data-faceping-token) or send the returned url to the person. Valid 30 minutes by default; validForHours (1 to 336) for emailed links, never past the end of a list with an end date. Returns 409 when enrolment is closed or the list has ended, when the list is full (a practice list holds 25 people, the pilot 500; links for someone already enrolled still work), or when no organisation name and privacy notice link are set (account Settings or this list's widget settings).

Parameters:

- `listId` (path): string (uuid), required

Request body: [CreateEnrollmentLinkRequest](#createenrollmentlinkrequest)

Responses:

- `201` Created: [EnrollmentLink](#enrollmentlink)
- `400` Bad Request: [ProblemMessage](#problemmessage)
- `404` Not Found
- `409` Conflict: [ProblemMessage](#problemmessage)
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.
- `415` The body wasn't sent as JSON: add Content-Type: application/json.

### Get a list's widget settings

`GET /v1/lists/{listId}/widget` (operationId `getWidgetSettings`)

The list's own organisation name, privacy notice link and brand colour. null means the list uses your account's value (dashboard Settings).

Parameters:

- `listId` (path): string (uuid), required

Responses:

- `200` OK: [WidgetSettings](#widgetsettings)
- `404` Not Found
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.

### Update a list's widget settings

`POST /v1/lists/{listId}/widget` (operationId `updateWidgetSettings`)

Optional: by default every list uses the enrolment page details from your account Settings. Each field here overrides the account value for this list only. A field you leave out (or send as null) stays as it is; send an empty string to clear it and fall back to the account. In the sandbox there are no account values, so a practice list needs its own organisation name and privacy notice link. organizationName is the name people know you by (up to 200 characters); privacyUrl must be https; brandColor looks like #0066ff. Enrolment links need an organisation name and privacy notice link from either place.

Parameters:

- `listId` (path): string (uuid), required

Request body: [WidgetSettings](#widgetsettings)

Responses:

- `200` OK: [WidgetSettings](#widgetsettings)
- `400` Bad Request: [ProblemMessage](#problemmessage)
- `404` Not Found
- `401` Missing, mistyped or revoked key. API keys (fp_) work once your account is live; sandbox keys (fp_test_) work on your practice list. A device token (fpd_) or enrolment token (fpe_) sent as a key is refused too. The body's message says which.
- `429` Too many requests (300 a minute per API key): wait and retry.
- `415` The body wasn't sent as JSON: add Content-Type: application/json.

## Schemas

### AddDeviceRequest

- `label`: string or null Example: `"North entrance, lane 2"`

### AddDeviceResponse

- `id`: string (uuid), required Example: `"8f2c4e1a-5b3d-4c6e-9a7f-1d2e3f405162"`
- `label`: string, required Example: `"North entrance, lane 2"`
- `prefix`: string, required Example: `"fpd_7Hk2mQ"`
- `token`: string, required Example: `"fpd_7Hk2mQ…"`
- `expiresAt`: string (date-time) or null, always present Example: `"2026-07-21T23:00:00+00:00"`

### CheckInList

- `id`: string (uuid), required Example: `"8f2c4e1a-5b3d-4c6e-9a7f-1d2e3f405162"`
- `name`: string, required Example: `"Summer Festival 2026"`
- `region`: string, required Example: `"eu"`
- `startsAt`: string (date-time), required Example: `"2026-07-18T09:00:00+00:00"`
- `endsAt`: string (date-time) or null, always present Example: `"2026-07-20T23:00:00+00:00"`
- `maxAgeMonths`: integer (int32) or null, always present
- `matchMode`: [MatchMode](#matchmode), required
- `retentionDays`: integer (int32) or null, always present Example: `7`
- `deleteAfter`: string (date-time) or null, always present Example: `"2026-07-27T23:00:00+00:00"`
- `enrollmentClosed`: boolean, required Example: `false`
- `peopleEnrolled`: integer (int32), required Example: `1240`
- `country`: string or null, always present Example: `"GB"`
- `consentVersion`: string, required Example: `"uk-v1"`
- `sandbox`: boolean Example: `false`

### CheckResultProblem

- `reason`: string, required Example: `"badSignature"`
- `message`: string, required Example: `"That list has ended, so it can't take new enrolments."`

### ConsentRequest

- `consentVersion`: string, required Example: `"uk-v1"`
- `givenAt`: string (date-time), required Example: `"2026-07-01T18:41:30+00:00"`
- `explicitBiometricConsent`: boolean, required Example: `true`
- `writtenRelease`: boolean Example: `false`
- `under16`: boolean Example: `false`
- `guardianConsent`: boolean Example: `false`

### CreateEnrollmentLinkRequest

- `personId`: string, required Example: `"TKT-004213"`
- `validForHours`: integer (int32) or null Example: `72`

### CreateListRequest

- `name`: string, required Example: `"Summer Festival 2026"`
- `alternativeEntryAvailable`: boolean, required Example: `true`
- `startsAt`: string (date-time) or null Example: `"2026-07-18T09:00:00+00:00"`
- `endsAt`: string (date-time) or null Example: `"2026-07-20T23:00:00+00:00"`
- `retentionDays`: integer (int32) or null Example: `7`
- `maxAgeMonths`: integer (int32) or null
- `matchMode`: [MatchMode](#matchmode) or null
- `country`: string or null Example: `"GB"`

### Device

- `id`: string (uuid), required Example: `"8f2c4e1a-5b3d-4c6e-9a7f-1d2e3f405162"`
- `label`: string, required Example: `"North entrance, lane 2"`
- `prefix`: string, required Example: `"fpd_7Hk2mQ"`
- `createdAt`: string (date-time), required Example: `"2026-06-02T10:15:00+00:00"`
- `revokedAt`: string (date-time) or null, always present
- `lastSyncAt`: string (date-time) or null, always present Example: `"2026-07-18T08:55:00+00:00"`
- `keyId`: string or null Example: `"_WrIS4adv2RkkXPLm7zYYA"`
- `publicKey`: [DevicePublicKey](#devicepublickey) or null
- `keyRegisteredAt`: string (date-time) or null Example: `"2026-07-17T16:20:00+00:00"`
- `keyMismatchAt`: string (date-time) or null

### DevicePublicKey

- `kty`: string, required Example: `"EC"`
- `crv`: string, required Example: `"P-256"`
- `x`: string, required Example: `"Sw6tOzaQUukdv7KVA2h1R7cEYyU2LmTCPZD430yVkK0"`
- `y`: string, required Example: `"cUoK2Oit0NW23k7u59cusZSPhwYwSLih53Cirw5WcuQ"`
- `kid`: string, required Example: `"_WrIS4adv2RkkXPLm7zYYA"`
- `alg`: string, required Example: `"ES256"`
- `use`: string, required Example: `"sig"`

### DeviceStatus

- `deviceId`: string (uuid), required Example: `"3b9d2f6e-1c4a-4e8b-a7d5-6f0e9c8b7a12"`
- `label`: string, required Example: `"North entrance, lane 2"`
- `listId`: string (uuid), required Example: `"8f2c4e1a-5b3d-4c6e-9a7f-1d2e3f405162"`
- `listName`: string, required Example: `"Summer Festival 2026"`
- `sandbox`: boolean, required Example: `false`
- `peopleEnrolled`: integer (int32), required Example: `1240`
- `expiresAt`: string (date-time) or null, always present Example: `"2026-07-21T23:00:00+00:00"`
- `lastSyncAt`: string (date-time) or null, always present Example: `"2026-07-18T08:55:00+00:00"`

### EnrollmentLink

- `token`: string, required Example: `"fpe_8wLzQ3…"`
- `expiresAt`: string (date-time), required Example: `"2026-07-21T23:00:00+00:00"`
- `url`: string, required Example: `"https://faceping.ai/enroll#t=fpe_…"`

### EnrollPersonRequest

- `personId`: string, required Example: `"TKT-004213"`
- `imageBase64`: string, required Example: `"/9j/4AAQSkZJRgABAQAAAQABAAD…"`
- `consent`: [ConsentRequest](#consentrequest), required

### EnrollPersonResponse

- `personId`: string, required Example: `"TKT-004213"`
- `modelId`: string, required Example: `"sface-2021dec-int8"`
- `deleteAfter`: string (date-time), required Example: `"2026-07-27T23:00:00+00:00"`

### ListConsentWording

- `consentVersion`: string, required Example: `"uk-v1"`
- `consent`: string, required
- `noticeConfirmation`: string, required
- `guardian`: string, required
- `privacyUrl`: string, required Example: `"https://harbourside.example/privacy"`

### MatchMode

One of: `Verify`, `Identify`


### PeoplePage

- `total`: integer (int32), required Example: `1240`
- `page`: integer (int32), required Example: `1`
- `people`: array of [Person](#person), required

### Person

- `personId`: string, required Example: `"TKT-004213"`
- `enrolledAt`: string (date-time), required Example: `"2026-07-01T18:42:00+00:00"`
- `source`: string, required Example: `"Api"`
- `consentVersion`: string, required Example: `"uk-v1"`
- `under16`: boolean, required Example: `false`
- `deleteAfter`: string (date-time) or null, always present Example: `"2026-07-27T23:00:00+00:00"`

### ProblemMessage

- `message`: string, required Example: `"That list has ended, so it can't take new enrolments."`

### UpdateListRequest

- `country`: string or null Example: `"GB"`
- `name`: string or null Example: `"Summer Festival 2026"`

### VerifiedCheckResult

- `match`: boolean, required Example: `true`
- `outcome`: string, required Example: `"match"`
- `personId`: string, required Example: `"TKT-004213"`
- `listId`: string (uuid), required Example: `"8f2c4e1a-5b3d-4c6e-9a7f-1d2e3f405162"`
- `deviceId`: string (uuid), required Example: `"3b9d2f6e-1c4a-4e8b-a7d5-6f0e9c8b7a12"`
- `deviceLabel`: string, required Example: `"North entrance, lane 2"`
- `live`: boolean, required Example: `true`
- `checkedAt`: string (date-time), required Example: `"2026-07-18T19:02:11+00:00"`
- `seq`: integer (int64), required Example: `412`
- `seqGap`: boolean, required Example: `false`
- `jti`: string, required Example: `"Jkc11zB_nkx8NJBzKPSqvQ"`
- `nonce`: string or null, always present Example: `"chk_5b1f0c9a2e"`
- `sdk`: string, required Example: `"flutter/1.0.0-preview.6"`
- `keyId`: string, required Example: `"_WrIS4adv2RkkXPLm7zYYA"`
- `deviceRevoked`: boolean, required Example: `false`
- `revokedAt`: string (date-time) or null, always present
- `verifiedAt`: string (date-time), required Example: `"2026-07-18T19:02:12+00:00"`

### VerifyCheckResultRequest

- `signedResult`: string or null, always present Example: `"eyJhbGciOiJFUzI1NiIsImtpZCI6Il9XcklTNGFkdjJSa2tYUExtN3pZWUEiLCJ0eXAiOiJmYWNlcGluZy1jaGVjaytqd3QifQ.eyJkZXYiOiIzYjlkMmY2ZS0xYzRhLTRlOGItYTdkNS02ZjBlOWM4YjdhMTIi…"`
- `nonce`: string or null Example: `"chk_5b1f0c9a2e"`

### WidgetSettings

- `organizationName`: string or null Example: `"Harbourside Events Ltd"`
- `privacyUrl`: string or null Example: `"https://harbourside.example/privacy"`
- `brandColor`: string or null Example: `"#2563EB"`
