Handle DocV Step-Up

Step 1: Detect the DocV step-up

Use this guide to handle DocV when an evaluation pauses and requires document capture before RiskOS™ can return a terminal decision.

Identify a DocV step-up by checking for all of the following in the evaluation response:

• decision = REVIEW
• status = ON_HOLD or eval_status = evaluation_paused
• data_enrichments contains an object where enrichment_provider = "SocureDocRequest"

Extract handoff assets

Locate the SocureDocRequest object and extract the following from response.data:

Example response

{
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "eval_status": "evaluation_paused",
  "data_enrichments": [
    {
      "enrichment_provider": "SocureDocRequest",
      "response": {
        "data": {
          "docvTransactionToken": "70c6a4bc-f646-4c6a-94c1-9cd428e356ef",
          "url": "https://verify.socure.com/..."
        }
      }
    }
  ]
}

What to do:

1. Locate the SocureDocRequest object in data_enrichments.
2. Extract docvTransactionToken from response.data.
3. Persist the eval_id and docvTransactionToken.
4. Send the token to your frontend and launch DocV.
5. Wait for the final result via webhook or updated evaluation.

Step 2: Launch the Document Verification Web SDK

The DocV Web SDK is a client-side JavaScript library that embeds the RiskOS™ document verification experience directly into your application.

It renders the Capture App, a secure mobile experience that guides the user through:

• Capturing a government-issued ID
• Taking a selfie
• Completing liveness verification

The Capture App UI is configurable from the DocV App page in the RiskOS™ Dashboard.

1. Include the DocV Web SDK script in your application.
2. Pass your SDK key (from the RiskOS™ Dashboard) and docvTransactionToken to SocureDocVSDK.launch().

Handoff options

Depending on your integration pattern, users can access the Capture App using:

1. QR code for desktop-to-mobile handoff
2. Secure SMS link for desktop or mobile
3. Mobile redirect URL using response.data.url

No resubmit: Treat DocV as a one-time step-up for the evaluation. If the step-up fails, RiskOS™ completes the evaluation and you should route the user to your fallback/manual flow (typically a final REJECT decision is delivered via webhook).

Step 3: Receive the final decision

DocV is asynchronous. After the Capture App flow completes, RiskOS™ resumes the paused evaluation and returns the final result.

Use one of the following approaches:

• Wait for an updated evaluation
• Receive the final result through a webhook event

To receive the final decision by webhook, configure a webhook endpoint on the Developer Workbench > Webhooks page in the RiskOS™ Dashboard.

Final routing

After DocV completes:

• Wait for the final decision
• Route based on the terminal response
• Do not re-submit DocV for the same evaluation

Routing outcomes:

• ACCEPT → Continue onboarding (for example, create account or grant access)
• REJECT → Route to your fallback, manual review, or decline flow

Example routing logic

if (data.decision === "ACCEPT") {
  router.push("/success");
}

if (data.decision === "REJECT") {
  router.push("/review");
}

Key takeaways

• Detect DocV using SocureDocRequest in data_enrichments.
• Persist eval_id and docvTransactionToken.
• Launch DocV once — do not re-submit for the same evaluation.
• Wait for the final decision before routing the user.

Error handling

If the API returns an HTTP error (4xx or 5xx), your application should handle it before processing any evaluation logic.

Data handling

What to persist

Store these fields for tracking: