Start identity verification

Unified entry point for starting an identity-verification job. channel selects the submission path and the rest of the body is that channel’s input:

server_upload: browser-captured selfie + ID submitted server-side to Smile ID Enhanced Document Verification (job_type 11) — keeps the government-database cross-check and captures the back of the ID. Returns the application status (202).
provider_sdk: mint a provider SDK session the client submits with directly — the hosted web SDK, or the v12 Android / iOS SDKs, which take the same token on network.config.token (or a SmartSelfie Authentication session for an already-enrolled user). Returns the provider session (201). The legacy spelling web_sdk is still accepted for this channel but should not be used by new clients. Supersedes POST /capture (server_upload) and POST /session (provider_sdk), which remain as aliases over the same engine. The pass/fail result arrives asynchronously via the provider callback, so the application is left ID_VERIFICATION_PENDING.

Declare the Smile ID SDK versions this client ships in X-SmileID-Api-Versions: the job runs against the newest one listed and stays on it for its whole life (config.api_version on a provider_sdk session says which).

Authorization

oauth2

AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Path Parameters

id*string

KYC application id.

Formatuuid

Header Parameters

X-SmileID-Api-Versions?string

Comma-separated Smile ID API versions this client’s bundled SDK can run, newest last or in any order (e.g. v2, v3). The job is started on the newest version listed that the server also speaks, and that version is pinned for the life of the job. Omitted, empty or unrecognised means v2 — so a client only upgrades when it says it can. Send the same value to the requirements GET and the verification POST: they resolve the version independently, and disagreeing between the two gets the capture rejected.

Request Body

application/json

Request to start identity verification. channel selects the submission path: server_upload submits a captured selfie and ID document server-side; provider_sdk mints a session for the client SDK to submit directly. web_sdk is a deprecated alias for provider_sdk.

channel*"server_upload"

Value in

"server_upload"

id_type?string

Document type code — one of the codes in GET /capture supported_documents for the active provider (e.g. IDENTITY_CARD = Kenyan national ID, PASSPORT). Sent to Smile ID as id_type. Required unless requires_document is false; omit it with document_front for a selfie-only capture.

Length1 <= length

country?string

ISO country code of the document. Defaults to KE.

Length2 <= length

selfie*string

Liveness selfie as a base64 image (raw base64 or a data: URL).

Length1 <= length

liveness_images?array<>

Liveness frames captured with the selfie by Smile ID’s smart-camera-web (published as image_type_id 6), each a base64 image (raw or a data: URL). Forward them to enable Smile ID’s active-liveness / anti-spoofing check; omit for a passive check on the selfie alone. At most 12.

Itemsitems <= 12

document_front?string

Front of the ID document as a base64 image. Required unless requires_document is false, in which case a selfie-only capture is re-verified against the applicant’s existing Smile ID enrollment. When it is missing but a document is needed, the request fails with INVALID_PARAMS and invalid_params[].sub_code DOCUMENT_REQUIRED.

Length1 <= length

document_back?string

Back of the ID document as a base64 image. Include when the chosen document type has has_back: true (e.g. the Kenyan national ID); omit for single-sided documents like passports.

Length1 <= length

consent?

The applicant’s consent, required when GET /capture reports requires_consent: true (the Smile ID V3 flow refuses a verification without it). Only the grant and its timestamp are accepted — the notice language and privacy-policy URL are server-configured and returned by GET /capture as consent_notice, which the client must display verbatim.

sandbox_result?string

Sandbox-only mock result code ("0" approve, "1" reject, "2" provisional). Ignored in production.

Response Body

`application/json`

curl -X POST "https://example.com/v1/kyc/applications/550e8400-e29b-41d4-a716-446655440000/verification" \  -H "Content-Type: application/json" \  -d '{    "channel": "server_upload",    "selfie": "string"  }'

{  "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",  "provider": "SMILE_ID",  "config": {    "property1": null,    "property2": null  }}

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "DRAFT",  "can_submit": true,  "needs_review": true,  "message": "string"}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

201application/json

202application/json

400application/json

401application/json

403application/json

404application/json

409application/json

413application/json

500application/json

502application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`