Cowdidocs
API ReferenceKYC

Create a resubmission

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

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

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

Optional body for granting a KYC application extra resubmission attempts.

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/resubmissions" \  -H "Content-Type: application/json" \  -d '{}'
{  "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"}
{  "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"    }  ]}

Reopen an expired application POST

Resets an `EXPIRED` application to `DRAFT` so the applicant can start verification again. Clears the provider session, the verification result, and the resubmission count. Returns 400 when the application is not `EXPIRED`. Call POST /applications/{id}/verification next to start a new attempt.

Review an application awaiting manual review POST

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