Cowdidocs
API ReferenceKyc

Start identity verification (unified entry point)

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).

POST
/v1/kyc/applications/{id}/verification

Authorization

Cowdi_Sales_KYC_backendBearerAuth
AuthorizationBearer <token>

Cowdi backend-compatible RS256 JWT. sub may be the global user id or a Firebase auth id; Firebase auth-id subjects and missing organization claims are resolved through the backend user/access endpoints. Validated against the configured JWKS (lib/backend-auth.ts).

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/kyc/applications/497f6eca-6276-4993-bfeb-53cbbbba6f08/verification" \  -H "Content-Type: application/json" \  -d '{    "channel": "server_upload",    "id_type": "IDENTITY_CARD",    "selfie": "string",    "document_front": "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"    }  ]}

Start a provider verification session (deprecated) POST

Deprecated — use POST /applications/{id}/verification with `channel: "provider_sdk"`. Kept as a thin alias over the same engine. Creates an identity-verification session with the active provider and moves the application to ID_VERIFICATION_PENDING. When Smile ID reports the merchant is already enrolled, the session is a SmartSelfie Authentication (config.mode = "authentication") that re-verifies the person against their enrolled face.

Create (or get) the caller’s KYC application POST

Creates a KYC application for the authenticated user, or returns the existing one if a non-terminal application already exists.