Verification Statuses: Session Lifecycle & Codes

Every verification session moves through a series of statuses. Understanding them helps you monitor user progress, automate compliance decisions, and optimize conversion. This enum is the single source of truth for the strings returned by GET /v3/session/<id>/decision/ and every Didit webhook.

All Status Values

Every status is an exact string returned by the Didit API and webhooks. Always use strict string matching (e.g., === "In Review") in your code — these values are case-sensitive and include spaces. The Kyc Expired value also uses a single capital K (not KYC).

Status	String Value	Description
Not Started	`"Not Started"`	Session created, user hasn’t opened the link
In Progress	`"In Progress"`	User is actively completing verification
Approved	`"Approved"`	All checks passed — identity verified
Declined	`"Declined"`	One or more checks failed
In Review	`"In Review"`	Flagged for manual compliance review
Awaiting User	`"Awaiting User"`	Waiting for one or more parties to complete their verification (KYB)
Resubmitted	`"Resubmitted"`	User asked to redo specific steps
Expired	`"Expired"`	Session timed out before user opened the link
Abandoned	`"Abandoned"`	User started but didn’t finish in time
KYC Expired	`"Kyc Expired"`	Previously approved session whose verified document passed its expiry date

Session Statuses

Not Started — "Not Started"

API value: "Not Started"The session has been created via the API but the user has not opened the verification link yet.

What to do: Wait for the user to begin, or send a reminder if too much time passes.
Transitions to: "In Progress", "Expired"

In Progress — "In Progress"

API value: "In Progress"The user has opened the link and is actively completing verification steps (document capture, liveness, etc.).

What to do: No action needed — the user is working through the flow.
Transitions to: "Approved", "Declined", "In Review", "Abandoned"

Approved — "Approved"

API value: "Approved"All verification checks passed successfully. The user’s identity has been verified.A reviewer can also link same-person KYC verifications during approval using link_to_session_id and a nonblank link_reason. Approval and linking succeed together. Grouping does not merge profiles or biometric data; deleting a verification removes it from the group. An already-approved session can gain a first link without another status event or email, and a same-group retry creates no additional link audit.

What to do: Grant the user access, update their profile, and store the decision data.
Webhook includes: Full decision object with all feature results.
Transitions to: "Kyc Expired" (when the verified document’s expiry date passes — the default unless Expiration mode is Allow expired for that country and document type). A reviewer or the update-status endpoint can also set it to "Declined" or "Resubmitted".

Declined — "Declined"

API value: "Declined"One or more verification checks failed. The user did not pass verification.

What to do: Notify the user. Optionally request a resubmission if the issue is fixable.
Webhook includes: Full decision object with warnings explaining the failure.
Transitions to: "Resubmitted" (if a reviewer requests it). A reviewer or the update-status endpoint can also set it to "Approved".

In Review — "In Review"

API value: "In Review"Automated checks flagged warnings that need human review. A compliance reviewer must make the final decision.

What to do: A reviewer should open the session in the Console and approve, decline, or request resubmission.
Webhook includes: Full decision object with warnings.
Transitions to: "Approved", "Declined", "Resubmitted"

Awaiting User — "Awaiting User"

API value: "Awaiting User"Used in KYB (business verification) sessions when the Key People step has submitted the list of parties and spawned child KYC / KYB sessions. The parent session waits until all required parties complete their individual verification.

What to do: Monitor the child KYC session statuses. Once all required parties finish (approved, declined, or expired), the parent session automatically re-aggregates to its final status.
Webhook includes: The current list of parties and their child session statuses.
Transitions to: "Approved", "Declined", "In Review" (once all child sessions are terminal)
Transitions from: "In Progress" (after the Key People step is submitted)
Note: If a child KYC session is resubmitted, the parent returns to "Awaiting User" until the resubmitted session completes. A "Declined" KYB Registry Check takes precedence over "Awaiting User".

Resubmitted — "Resubmitted"

API value: "Resubmitted"A reviewer has requested that the user redo specific verification steps (e.g., retake a blurry document photo).

What to do: Wait for the user to complete the resubmitted steps. The system will automatically re-evaluate.
Webhook includes: resubmit_info object with the list of features to redo and reasons.
Transitions to: "Approved", "Declined", "In Review", or "Abandoned" when the session window ends before the person redoes the steps.

Expired — "Expired"

API value: "Expired"The session timed out before the user opened the verification link.

What to do: Create a new session and send the user a fresh link.
Terminal status — no further transitions.

Abandoned — "Abandoned"

API value: "Abandoned"The user started but did not finish the verification within the allowed timeframe.

What to do: Send a reminder or create a new session.
No automatic transitions. A reviewer, or PATCH /v3/session/{sessionId}/update-status/, can still set it to "Approved", "Declined" or "Resubmitted".

KYC Expired — "Kyc Expired"

API value: "Kyc Expired"The document verified during the session has passed its own expiry date. The trigger is that date, not a window measured from approval, and no warning is sent beforehand.

What to do: Ask the user to re-verify with a new session. status.updated delivers the transition, and the ID verification result carries a DOCUMENT_EXPIRED warning.
Controlled by: the Expiration mode of that country and document type in ID verification → Additional settings by country & document type — Reject expired (the default) monitors the document, Allow expired means the session never moves here.
No automatic transitions. A reviewer, or PATCH /v3/session/{sessionId}/update-status/, can still set it to "Approved", "Declined" or "Resubmitted".

Status Transitions

From	To	Trigger
`"Not Started"`	`"In Progress"`	User opens the verification link
`"Not Started"`	`"Expired"`	Session TTL elapses before the user opens the link
`"In Progress"`	`"Approved"`	All automated checks pass
`"In Progress"`	`"Declined"`	One or more checks fail
`"In Progress"`	`"In Review"`	Checks flag warnings requiring human review
`"In Progress"`	`"Awaiting User"`	KYB Key People step submitted; parent waits for child KYC parties
`"In Progress"`	`"Abandoned"`	User doesn’t finish within the timeframe
`"Awaiting User"`	`"Approved"`	All required KYB parties finish and aggregated checks pass
`"Awaiting User"`	`"Declined"`	A required party is declined or the KYB registry check fails
`"Awaiting User"`	`"In Review"`	Aggregated KYB result requires manual review
`"In Review"`	`"Approved"`	Reviewer manually approves
`"In Review"`	`"Declined"`	Reviewer manually declines
`"In Review"`	`"Resubmitted"`	Reviewer requests specific steps to be redone
`"Declined"`	`"Resubmitted"`	Reviewer requests specific steps to be redone
`"Approved"`	`"Resubmitted"`	Reviewer requests specific steps to be redone
`"Approved"`	`"Declined"`	Reviewer or API sets the other decision
`"Declined"`	`"Approved"`	Reviewer or API sets the other decision
`"Abandoned"`, `"Kyc Expired"`	`"Approved"`, `"Declined"`, `"Resubmitted"`	Reviewer or API decides a session that ended without a decision
`"Resubmitted"`	`"Abandoned"`	The session window ends before the person redoes the steps
`"Resubmitted"`	`"Approved"`	Resubmitted steps pass all checks
`"Resubmitted"`	`"Declined"`	Resubmitted steps fail
`"Resubmitted"`	`"In Review"`	Resubmitted steps flag new warnings
`"Resubmitted"` (KYB child)	`"Awaiting User"` (KYB parent)	Parent re-enters waiting state until child completes
`"Approved"`	`"Kyc Expired"`	The verified document’s expiry date passes (Expiration mode is Reject expired)

Lifecycle diagram

Terminal vs Non-Terminal

Category	Statuses	Meaning
Decided	`"Approved"`, `"Declined"`, `"Kyc Expired"`	The checks produced a decision and nothing changes it on its own, except `"Approved"` → `"Kyc Expired"` when the verified document’s expiry date passes. A reviewer or the update-status endpoint can still change the decision.
Non-Terminal	`"Not Started"`, `"In Progress"`, `"Resubmitted"`, `"Awaiting User"`	Still active — awaiting user action, child sessions, or processing.
Actionable	`"In Review"`	Requires manual intervention from your team.
Inactive	`"Expired"`, `"Abandoned"`	Ended without a verification decision. `"Expired"` never changes; a reviewer can still decide an `"Abandoned"` session.

Handling Statuses in Your Code

Use webhooks or the Retrieve Session API to react to status changes.

Statuses are exact, case-sensitive strings with spaces. For example, "In Review" (not "in_review" or "IN_REVIEW"). Always use strict equality (===) when matching.

// All ten possible status string values (StatusChoices, source of truth):
// "Not Started"  | "In Progress" | "Approved"     | "Declined" |
// "In Review"    | "Resubmitted" | "Awaiting User"|
// "Expired"      | "Abandoned"   | "Kyc Expired"

async function handleWebhook(webhook) {
  const { status, vendor_data: vendorData } = webhook;

  switch (status) {
    case "Not Started":
      // Session created but user hasn't opened the link yet
      break;

    case "In Progress":
      // User is actively completing verification steps
      break;

    case "Approved":
      // All checks passed — grant access
      await db.users.update(vendorData, {
        verified: true,
        verifiedAt: new Date(),
        decision: webhook.decision,
      });
      break;

    case "Declined":
      // Verification failed — notify user
      await db.users.update(vendorData, {
        verificationStatus: "declined",
        declineReasons: webhook.decision?.warnings,
      });
      break;

    case "In Review":
      // Needs manual review by compliance team
      await db.users.update(vendorData, {
        verificationStatus: "pending_review",
      });
      break;

    case "Awaiting User":
      // KYB parent waiting for all child KYC parties to finish
      await db.users.update(vendorData, {
        verificationStatus: "awaiting_kyb_parties",
      });
      break;

    case "Resubmitted":
      // User will redo specific steps
      await db.users.update(vendorData, {
        verificationStatus: "resubmission_pending",
        resubmitInfo: webhook.resubmit_info,
      });
      break;

    case "Abandoned":
      // User started but didn't finish — send reminder
      await sendReminderEmail(vendorData);
      break;

    case "Expired":
    case "Kyc Expired":
      // Session expired — create a new one
      await createNewSession(vendorData);
      break;
  }
}

Resubmission

The Resubmitted status lets your compliance team give users a second chance without creating a new session.

Reviewer initiates resubmission

From the Console, open an In Review or Declined session and click Request Resubmission. Select which steps need to be redone.

Previous data is archived

The system resets the selected features and marks prior data as previous_attempt — preserving the full audit trail.

User is notified

If an email is available, the user receives a localized email with a direct link to resume.

User redoes specific steps

The user only repeats the steps that were flagged — not the entire verification.

System re-evaluates

Once complete, the session automatically transitions to "Approved", "Declined", or "In Review".

Resubmission Webhook Payload

{
  "session_id": "uuid-of-the-session",
  "status": "Resubmitted",
  "resubmit_info": {
    "nodes_to_resubmit": [
      { "node_id": "feature_ocr", "feature": "OCR" },
      { "node_id": "feature_liveness", "feature": "LIVENESS" }
    ],
    "reasons": {
      "feature_ocr": "DOCUMENT_EXPIRED",
      "feature_liveness": "LOW_LIVENESS_SCORE"
    }
  }
}

reasons maps each resubmitted node_id to the warning code of the most relevant log on that step (the same codes the decision reports), so you can map it to your own copy. It is also the code the hosted flow’s resubmission screen and the resubmission email localize for the user, except for warnings that would reveal a screening or fraud signal (duplicates, AML, blocklist, cross-organization checks, location integrity and similar): for those the person sees a generic reason, and resubmit_info.reasons in your webhook always carries the real code. A step with no recorded warning has no entry.

Which Features Can Be Resubmitted?

Any feature with a non-approved status: Declined, In Review, Not Finished, Not Started, or Expired.

You can request resubmission multiple times on the same session. Each cycle archives the previous attempt data, giving you complete visibility into the user’s verification history.

Best Practices

Monitor In Review

Set up alerts (email or Slack) in your Didit Console to get notified when sessions need manual review.

Prefer Resubmission

If the issue is fixable (blurry photo, wrong document side), request a resubmission instead of declining. This improves conversion.

Track Drop-offs

High Abandoned or Expired rates may indicate UX friction. Consider adjusting session TTL or improving user guidance.

Idempotent Handlers

Webhooks may be retried. Use session_id as a unique key to ensure you process each status change only once.

Always verify webhook signatures before processing payloads. Didit provides three methods: X-Signature, X-Signature-V2 (recommended), and the deprecated X-Signature-Simple, which authenticates the envelope only and never the decision body. See Webhooks for details.

Guides

Authentication

Model Context Protocol (MCP)

Web SDKs

Native SDKs

Server SDKs

Integrations

Verification Statuses: Session Lifecycle & Codes

All Status Values

Session Statuses

Status Transitions

Lifecycle diagram

Terminal vs Non-Terminal

Handling Statuses in Your Code

Resubmission

Resubmission Webhook Payload

Which Features Can Be Resubmitted?

Best Practices

Monitor In Review

Prefer Resubmission

Track Drop-offs

Idempotent Handlers