Skip to main content
PATCH
curl

KYC and KYB support

This endpoint works identically for User Verification (KYC) and Business Verification (KYB) sessions. Didit resolves the session_id against both session types; status-transition validation is the same for both (the same enum of statuses applies to both). The response includes session_kind so your downstream logic can switch on the outcome kind.

Allowed transitions

You can move a session to APPROVED, DECLINED, IN_REVIEW, or RESUBMITTED. The session’s current status must be one of: APPROVED, DECLINED, IN_REVIEW, KYC_EXPIRED, ABANDONED, or RESUBMITTED — otherwise the API returns a validation error. A resubmit whose nodes_to_resubmit contain only backend-only features (AML, DATABASE_VALIDATION, IP_ANALYSIS) executes automatically and returns the session to a decided status with no user interaction. Repeating such a resubmit within 30 seconds returns 429 Too Many Requests with a Retry-After header, since an immediate repeat cannot produce a different result. Do not auto-resubmit from a webhook handler whenever you receive an In Review status - review the finding or change the underlying data first.

Examples

Permission

Requires the write:sessions privilege. The same privilege covers both kinds.

Authorizations

x-api-key
string
header
required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is missing, wrong, revoked or expired; 403 means the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Path Parameters

sessionId
string<uuid>
required

UUID of the verification session to update. Accepts both user (KYC) and business (KYB) session IDs — the service resolves the ID across both session types.

Example:

"11111111-2222-3333-4444-555555555555"

Body

application/json
new_status
enum<string>
required

Target status. Approved and Declined record a final manual decision (each can also overturn the other). Resubmitted clears the selected steps and sends the session back to the user. Any other value returns 400.

Available options:
Approved,
Declined,
Resubmitted
Example:

"Approved"

comment
string

Free-text reason for the change, stored on the session's review trail and returned in the reviews array of Get Decision. For example Duplicated user.

Example:

"All checks passed manual review"

nodes_to_resubmit
object[]

Workflow steps the user must redo. Only acted on when new_status is Resubmitted. For Approved/Declined the entries are still schema-validated (an invalid feature value returns 400) but schema-valid entries are semantically ignored. If omitted, the server auto-selects existing OCR, Liveness, Face Match, POA, Phone, Email, AML, Database Validation, and Questionnaire attempts whose status is Declined, In Review, Not Finished, or Expired (NFC, IP analysis, age estimation, face search, and KYB document attempts are never auto-selected; non-face-match face attempts are selected as LIVENESS) — features the user never attempted (no recorded attempt) are NOT selected, so a session with zero attempts returns 400 ("No features found that need resubmission") even though nothing was approved; pass nodes_to_resubmit explicitly in that case. Steps are executed in workflow-graph order regardless of the order you send them. KYB_REGISTRY, KYB_KEY_PEOPLE, and the KYB alias are rejected with 400 — those parent checks recompute from their child KYC sessions.

send_email
boolean
default:false

Whether to email the user about the change. Requires email_address. For Approved/Declined the user receives a status notice; for Resubmitted the email includes the verification link and the per-step resubmission reasons.

Example:

false

email_address
string<email>

Recipient for the notification email. Required when send_email is true — omitting it returns 400.

Example:

"user@example.com"

email_language
string
default:en

Language for the notification email. Accepts any string at schema level; unsupported codes silently fall back to English (en).

Example:

"en"

email_preview_token
string
write-only

Optional signed receipt from Preview Resubmission Email. When supplied with send_email=true and new_status=Resubmitted, the recipient, language, checks, current session state, sender and message must still match the preview. A changed or expired receipt returns 409 before changing the session or sending email. Existing integrations may omit this field.

Required string length: 1 - 512

Response

Status updated. The response contains only the session_id — fetch the updated session via Get Decision. The status.updated webhook fires once the change commits.

session_id
string<uuid>

UUID of the updated session.