Verification Statuses

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 exceeded KYC expiration

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.

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" (if a KYC expiration policy is configured)

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)

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"

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.
Terminal status — no further transitions.

KYC Expired — "Kyc Expired"

API value: "Kyc Expired"A previously approved session has exceeded the configured KYC expiration period (e.g., 12 months).

What to do: Request the user to re-verify by creating a new session.
Terminal status — no further transitions.

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
`"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"`	KYC expiration policy triggers

Lifecycle diagram

Terminal vs Non-Terminal

Category	Statuses	Meaning
Terminal	`"Approved"`, `"Declined"`, `"Kyc Expired"`	Final decision — session won’t change again, except `"Approved"` → `"Kyc Expired"` when a KYC expiration policy applies.
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.

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 image is blurry or unreadable",
      "feature_liveness": "Liveness check score below threshold"
    }
  }
}

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 X-Signature-Simple. See Webhooks for details.

Guides

Model Context Protocol (MCP)

Web SDKs

Native SDKs

Integrations

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

​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

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