Cowdidocs
API ReferenceKyc

Submit a captured selfie + ID for verification (deprecated)

Deprecated — use POST /applications/{id}/verification with `channel: "server_upload"`. Kept as a thin alias over the same engine. Server-side capture-then-submit: the browser captures a liveness selfie (with its liveness frames) and the ID document (front + optional back) with Smile ID’s smart-camera-web component and POSTs the base64 images here. They are submitted server-side to Smile ID Enhanced Document Verification (job_type 11) — keeping the government database cross-check while also capturing the back of the ID, which the hosted widget cannot. Include `liveness_images` to run Smile ID’s active-liveness / anti-spoofing check (a lone selfie only gets the passive check). The result arrives asynchronously via the provider callback, so the application is left ID_VERIFICATION_PENDING.

Deprecated

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

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

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

Run the KYC stale-session expiry sweep for an organization POST

Runs the stale-session expiry sweep for the caller’s organization. The service also runs this job on its own schedule across every organization; this endpoint is the operator-triggered form, narrowed to one tenant. The sweep reconciles applications that have sat in ID_VERIFICATION_PENDING past the provider submission window: a job the provider reports as final is completed, and one the provider no longer knows about is moved to EXPIRED — nothing is expired without asking the provider first. Authenticated with an internal user’s backend bearer token and authorized against backend RBAC (accounts.write at ORG scope for the caller’s own organization, or PLATFORM). The organization is resolved from the token; passing organization_id is rejected. The run is held to the same interval as the scheduled one — there is no force bypass — and each organization has its own lease and due-window, so a manual run neither blocks nor is blocked by the global schedule.

Send an application back to DRAFT POST

Admin override that resets an application to DRAFT from any status, clearing the provider session, verification result, rejection reason and reapply cooldown so it can re-run verification from scratch. resubmission_count is preserved. Optionally set `force_new_enroll` to make the applicant’s next Smile ID session a fresh enrollment (overwriting the enrolled biometric). Org-scoped and gated on the backend `accounts.write` permission (override with KYC_REVIEWER_PERMISSION).