LegitFlash

API reference

TrustID API · v1.0.0 · openapi.json

Create identity-verification sessions, send the applicant to the hosted link, then receive the signed webhook and fetch the result. Personal-token API: send Authorization: Bearer <token> (Account → API tokens). Tokens act as their owner, carry abilities (read/write for the account routes; sessions:read, sessions:write, flows:read, webhooks:read for verifications) and always expire. A tid_live_… token works on real sessions; a tid_test_… token only on test sessions (livemode: false: a simulator replaces the capture, nothing is reviewed or billed, data is deleted after 24 hours). Every POST accepts an Idempotency-Key header. Metadata must never hold personal data. Tenant routes take the team from the X-Team-Id header, required when the user belongs to more than one team. Errors are RFC 9457 application/problem+json. Ids are ULIDs, timestamps ISO-8601 UTC, money integer cents plus a currency, lists cursor-paginated. Requests are rate limited per token by plan (X-RateLimit-*, 429 + Retry-After).

Meta

GET /openapi.json

This document

Responses

  • 200 The OpenAPI document

Account

The token's owner. No team needed.

GET /me

The token's owner and the token itself

Token abilities: read

Responses

  • 200 Owner and token
    Name Type Description
    id* string ULID
    name* string
    email* string (email)
    locale* string
    timezone* string
    created_at* string (date-time)
    token* object|null
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

GET /teams

Teams the user belongs to (their ids go in X-Team-Id)

Token abilities: read

Parameters

Name In Type Description
cursor query string Opaque cursor from `links.next` / `meta.next_cursor`.

Responses

  • 200 A page of teams
    Name Type Description
    data* array<Team>
    links* object
    meta* object
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

Team

The team picked by X-Team-Id. Needs a plan with API access.

GET /team

The current team, your role and its plan

Token abilities: read

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.

Responses

  • 200 The team, with your role, and its plan in meta
    Name Type Description
    data* Team
    meta* object
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 404 Not found, including a team you are not a member of (`team_not_found`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

PATCH /team

Rename the current team (owner or admin role)

Token abilities: write

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.

Request body (JSON)

Name Type Description
name* string

Responses

  • 200 The team, with your role, and its plan in meta
    Name Type Description
    data* Team
    meta* object
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 404 Not found, including a team you are not a member of (`team_not_found`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 422 Invalid fields (`validation_failed`); see `errors`
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

Flows

The verification flows of the team (read only).

GET /flows

List the flows of the team

Token abilities: flows:read

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.
cursor query string Opaque cursor from `links.next` / `meta.next_cursor`.
per_page query integer
archived query boolean `true` only archived, `false` only active; omit for both.

Responses

  • 200 A page of flows
    Name Type Description
    data* array<Flow>
    links* object
    meta* object
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 422 Invalid fields (`validation_failed`); see `errors`
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

GET /flows/{id}

One flow

Token abilities: flows:read

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.
id* path string Flow id (ULID).

Responses

  • 200 The flow
    Name Type Description
    id string
    name string
    steps object
    documents object|null
    min_age integer|null
    result_detail full | minimal
    max_resubmissions integer
    link_ttl_hours integer
    locale_default string
    ready boolean Can create sessions (has a privacy policy URL).
    archived boolean
    archived_at string|null (date-time)
    created_at string|null (date-time)
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 404 Not found, including a team you are not a member of (`team_not_found`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

Sessions

Verification sessions. A test token creates and sees only test sessions (livemode: false); a live token only live ones.

GET /sessions

List sessions (newest first, cursor pagination)

Token abilities: sessions:read

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.
cursor query string Opaque cursor from `links.next` / `meta.next_cursor`.
per_page query integer
status query created | in_progress | submitted | in_review | approved | rejected | resubmission_requested | expired | cancelled
flow_id query string
external_reference query string
created query object Filter on created: `created[gte]` / `created[lte]`, ISO-8601.
decided query object Filter on decided: `decided[gte]` / `decided[lte]`, ISO-8601.

Responses

  • 200 A page of sessions
    Name Type Description
    data* array<Session>
    links* object
    meta* object
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 422 Invalid fields (`validation_failed`); see `errors`
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

POST /sessions

Create a session and get its hosted link

Token abilities: sessions:write

Returns 201 with the session plus url (the hosted link), qr_svg_url (signed, 15 minutes) and embed. The link is shown only in this response and in POST /sessions/{id}/link; only a hash of it is stored. A test token creates a test session (simulator, no review, no billing, deleted after 24 h).

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.
Idempotency-Key header string Up to 255 characters. The same key with the same request within 24 hours replays the first response (`Idempotent-Replayed: true`); the same key with a different request is a `422` (`idempotency_key_reused`).

Request body (JSON)

Name Type Description
flow_id* string ULID of an active flow that has a privacy policy URL.
external_reference string|null Your own reference (order, booking...). Echoed in every response and webhook.
applicant object|null
locale en | es |
send_invite boolean Email the link to `applicant.email` (live mode only).
redirect_url string|null (uri) Where to send the applicant afterwards. Its host must be one of the hosts of the flow's redirect URLs.
metadata object|null Up to 10 string pairs of at most 500 bytes. **Do not put personal data here.**

Responses

  • 201 Session created
    Name Type Description
    id* string
    livemode* boolean
    flow_id* string
    flow_name string|null
    external_reference string|null
    metadata object|null
    status* created | in_progress | submitted | in_review | approved | rejected | resubmission_requested | expired | cancelled
    decision approved | rejected |
    reason_codes array<string>
    round* integer
    locale string
    resubmission_items array|null
    created_at* string (date-time)
    expires_at string|null (date-time)
    submitted_at string|null (date-time)
    decided_at string|null (date-time)
    media_purge_at string|null (date-time)
    url* string (uri) The hosted link. Shown only here and in `POST /sessions/{id}/link`.
    qr_svg_url* string (uri) Signed URL of an SVG QR code of the link, valid 15 minutes.
    embed* object
    invite queued | suppressed |
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 422 Invalid fields (`validation_failed`); see `errors`
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

GET /sessions/{id}

One session: status, decision, reason codes, subject fields, checks and timeline (no media)

Token abilities: sessions:read

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.
id* path string Session id (ULID).

Responses

  • 200 The session
    Name Type Description
    id* string
    livemode* boolean
    flow_id* string
    flow_name string|null
    external_reference string|null
    metadata object|null
    status* created | in_progress | submitted | in_review | approved | rejected | resubmission_requested | expired | cancelled
    decision approved | rejected |
    reason_codes array<string>
    round* integer
    locale string
    resubmission_items array|null
    created_at* string (date-time)
    expires_at string|null (date-time)
    submitted_at string|null (date-time)
    decided_at string|null (date-time)
    media_purge_at string|null (date-time)
    result object|null Present once decided. A minimal-result flow only carries the `age_over_*` booleans.
    checks object|null Flag names of the latest automatic pre-check; never metrics.
    timeline array<object>
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 404 Not found, including a team you are not a member of (`team_not_found`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

DELETE /sessions/{id}

Erase the session and its media now (data-subject erasure)

Token abilities: sessions:write

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.
id* path string Session id (ULID).

Responses

  • 204 Erased
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 404 Not found, including a team you are not a member of (`team_not_found`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

POST /sessions/{id}/cancel

Cancel a session that has not been submitted

Token abilities: sessions:write

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.
id* path string Session id (ULID).
Idempotency-Key header string Up to 255 characters. The same key with the same request within 24 hours replays the first response (`Idempotent-Replayed: true`); the same key with a different request is a `422` (`idempotency_key_reused`).

Responses

  • 200 The cancelled session
    Name Type Description
    id* string
    livemode* boolean
    flow_id* string
    flow_name string|null
    external_reference string|null
    metadata object|null
    status* created | in_progress | submitted | in_review | approved | rejected | resubmission_requested | expired | cancelled
    decision approved | rejected |
    reason_codes array<string>
    round* integer
    locale string
    resubmission_items array|null
    created_at* string (date-time)
    expires_at string|null (date-time)
    submitted_at string|null (date-time)
    decided_at string|null (date-time)
    media_purge_at string|null (date-time)
    result object|null Present once decided. A minimal-result flow only carries the `age_over_*` booleans.
    checks object|null Flag names of the latest automatic pre-check; never metrics.
    timeline array<object>
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 404 Not found, including a team you are not a member of (`team_not_found`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 409 The session is in a status that does not allow this (`not_cancellable`, `not_relinkable`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

POST /sessions/{id}/link

Issue a new hosted link (the old one stops working)

Token abilities: sessions:write

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.
id* path string Session id (ULID).
Idempotency-Key header string Up to 255 characters. The same key with the same request within 24 hours replays the first response (`Idempotent-Replayed: true`); the same key with a different request is a `422` (`idempotency_key_reused`).

Responses

  • 200 The session with its new link
    Name Type Description
    id* string
    livemode* boolean
    flow_id* string
    flow_name string|null
    external_reference string|null
    metadata object|null
    status* created | in_progress | submitted | in_review | approved | rejected | resubmission_requested | expired | cancelled
    decision approved | rejected |
    reason_codes array<string>
    round* integer
    locale string
    resubmission_items array|null
    created_at* string (date-time)
    expires_at string|null (date-time)
    submitted_at string|null (date-time)
    decided_at string|null (date-time)
    media_purge_at string|null (date-time)
    url* string (uri) The hosted link. Shown only here and in `POST /sessions/{id}/link`.
    qr_svg_url* string (uri) Signed URL of an SVG QR code of the link, valid 15 minutes.
    embed* object
    invite queued | suppressed |
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 404 Not found, including a team you are not a member of (`team_not_found`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 409 The session is in a status that does not allow this (`not_cancellable`, `not_relinkable`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

GET /sessions/{id}/export

Data-subject access export (JSON, no media binaries)

Token abilities: sessions:read

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.
id* path string Session id (ULID).

Responses

  • 200 Everything held about the session
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 404 Not found, including a team you are not a member of (`team_not_found`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

Usage

Billable verifications of the current month.

GET /usage

Billable verifications of the current month

Token abilities: sessions:read

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.

Responses

  • 200 Usage
    Name Type Description
    period string (date) First day of the billing month.
    included integer|null
    used integer
    overage integer
    cap integer|null
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

Webhooks

Delivery status of the webhooks the platform sent you.

GET /webhook-deliveries

Delivery status of webhooks, for debugging (no payloads)

Token abilities: webhooks:read

Parameters

Name In Type Description
X-Team-Id header string ULID of the team. Required when the user belongs to more than one team; otherwise their only team is used.
cursor query string Opaque cursor from `links.next` / `meta.next_cursor`.
per_page query integer
session_id query string
status query pending | delivered | failed

Responses

  • 200 A page of deliveries
    Name Type Description
    data* array<WebhookDelivery>
    links* object
    meta* object
  • 400 You belong to several teams and sent no X-Team-Id (`team_required`), or a token was sent in the query string (`token_in_query`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 401 No token, an unknown, expired or revoked one, or its owner is suspended (`unauthenticated`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 403 The token lacks the ability (`missing_ability`), the role doesn't allow it (`forbidden`), the plan has no API access or the team is suspended (`team_suspended`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 422 Invalid fields (`validation_failed`); see `errors`
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.
  • 429 Rate limit of the token's plan reached (`rate_limited`)
    Name Type Description
    type* string
    title* string
    status* integer
    detail* string
    code* string Stable machine-readable reason.
    request_id* string|null Quote it when contacting support.
    errors object Only on 422: field → messages.

Webhook events

sessionEvent

Event sent to your endpoint (configure it in Developers → Webhooks)

Header TrustId-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256 of <t>.<raw body> with your endpoint secret (two values during the 24 h after a rotation). Reject timestamps older than 5 minutes. Other headers: TrustId-Event, TrustId-Delivery. Answer 2xx within 10 seconds; otherwise it is retried (1 m, 5 m, 30 m, 2 h, 6 h, 12 h, 24 h). Events: session.created, session.started, session.submitted, session.approved, session.rejected, session.resubmission_requested, session.decision_changed, session.expired, session.cancelled, session.media_purged, session.erased (only data.session_id and data.erased_at), webhook.test. Test-mode sessions send the same events with livemode: false.

Name Type Description
id* string
type* string
created_at* string (date-time)
livemode* boolean
data* object Session id, external_reference, metadata, flow_id, status, decision, reason_codes, round, resubmission_items, age_over_* booleans, timestamps and (full-result flows) `document` and `subject`. Never media, URLs or the applicant's email.