Cowdidocs
API ReferenceKYC

Review an application awaiting manual review

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

Privileged reviewer action on an application in PENDING_MANUAL_REVIEW. approve moves it to APPROVED; reject moves it to REJECTED; request_resubmission returns it to DRAFT so the applicant can re-run verification. approve is accepted only when the merchant subject carries every identity field backend onboarding requires (name, date_of_birth, gender, id_number, phone) — a failed document read extracts none of them, so the reviewer fills the gaps via the internal subject editor first; otherwise the approve is rejected with 409 listing the missing fields. Org-scoped (not owner-scoped) and gated on the WorkOS org:kyc.override:write permission, checked on the caller organization (override with KYC_REVIEWER_PERMISSION).

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

Request Body

application/json

Reviewer decision on a KYC application awaiting manual review.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/kyc/applications/550e8400-e29b-41d4-a716-446655440000/review" \  -H "Content-Type: application/json" \  -d '{    "action": "approve",    "reason": "ID document photo was blurry; please re-upload a clearer image."  }'
{  "id": "550e8400-e29b-41d4-a716-446655440000",  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",  "organization_id": "cowdi",  "user_type": "INDIVIDUAL",  "merchant_type": "SOLE_PROPRIETOR",  "status": "DRAFT",  "source": "USER",  "documents": [    {      "id": "3fa2c1d4-8b8e-4c9a-9c9e-1f2e3a4b5c6d",      "document_type": "NATIONAL_ID",      "document_sub_type": "string",      "document_number": "string",      "expiry_date": "string",      "presigned_url": "string",      "uploaded_at": "2026-06-04T10:20:00.000Z"    }  ],  "verification": {    "provider": "SMILE_ID",    "provider_job_id": "string",    "result": "PASSED",    "confidence_score": 0,    "completed_at": "2026-06-04T10:20:00.000Z"  },  "verification_reason_code": "string",  "external_reason_code": "DOCUMENT_IMAGE_UNUSABLE",  "external_reason": "Part of your ID document was cut off. Retake the photo with all four corners of the document inside the frame.",  "resubmission_count": 0,  "force_new_enroll": true,  "reapply_blocked_until": "2026-06-04T10:20:00.000Z",  "submitted_at": "2026-06-04T10:20:00.000Z",  "created_at": "2026-06-04T10:20:00.000Z",  "updated_at": "2026-06-04T10:20:00.000Z",  "verification_reason": "string",  "rejection_reason": "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"    }  ]}

Create a resubmission POST

Admin override that un-blocks exactly one more attempt for an application in REJECTED or PENDING_MANUAL_REVIEW: it returns to DRAFT (provider state and reapply cooldown cleared) so it can re-run verification once. The resubmission cap re-applies afterwards, so each created resubmission grants one attempt; 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).

Start a provider verification session 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. Answers with a `Deprecation` header and a `Link` to the Versions page.