Skip to content

Mint a capture-widget session token for a KYC check

POST/v1/kyc/checks/{id}/capture-session

Requires an API client bearer token.

Returns a 15-minute bearer token valid for repeated captures until expiry or the check leaves `collecting`. Use `capture_url` as the iframe `src` — it embeds the token in the URL fragment, which must not be logged. Hand the session only to the hosted capture widget — never your own OAuth client credentials — so the widget can post captured document images to the vision service on your behalf. Mintable while the check is collecting; a default `"document"` session is also mintable while the check is `evaluating` if a reviewer has opened a re-capture window on it. Optionally pass `{ "kind": "selfie" }` to mint a selfie-capture session instead — selfie sessions remain mintable only while the check is collecting, regardless of any re-capture window. Optionally pass `{ "kind": "flow" }` to mint a session for the applicant's whole outstanding journey (details, document, selfie as the programme's policy requires); mintable only while collecting. Optionally pass `theme` (`"light"` or `"dark"`) to pin the hosted page to your app's appearance — omitted, the page follows the end user's device via `prefers-color-scheme`. Optionally pass `document_type` (`"passport"`, `"national_id"`, `"residence_permit"`, or `"driving_licence"`) for a `"document"`- or `"flow"`-kind session — omitted, it defaults to `"passport"` — and it is echoed back in the response. Requesting a non-passport class 400s `document_class_unavailable` in an environment with no document-extraction provider configured. `document_class_not_accepted` 400s for ANY class — including the passport default — the programme's policy does not accept via `accepted_document_types`. `document_type` is ignored for a selfie session.

Parameters

Path parameters

NameRequiredDescription
idrequired

Request body

kind"document" | "selfie" | "flow"
theme"light" | "dark"
document_type"passport" | "national_id" | "residence_permit" | "driving_licence"

Example

curl -X POST https://api.rigid.fi/v1/kyc/checks/{id}/capture-session \
  -H "Authorization: Bearer $RIGID_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "document",
  "theme": "light",
  "document_type": "passport"
}'

Responses

200

A capture session token and ready-made iframe URL.

tokenstringrequired
expires_atstring (date-time)required
session_idstringrequired
capture_urlstring (uri)required
kind"document" | "selfie" | "flow"required
theme"light" | "dark"
document_type"passport" | "national_id" | "residence_permit" | "driving_licence"required
400

Validation error

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
401

Authentication required

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
403

Forbidden

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
404

KYC check not found

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
500

Internal server error

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring