Handle Additional Verification

Use this page to handle step-up verification when an evaluation requires additional user input or identity verification.

Additional verification can take two forms:

• One-Time Passcode (OTP)
• Predictive Document Verification (DocV)

For response handling patterns, see Handle Results.

Overview

RiskOS™ pauses an evaluation when additional verification is required.

Common signals:

• One-Time Passcode: status = ON_HOLD, sub_status = Awaiting Customer OTP
• Additional PII: sub_status = More information needed
• DocV: Evaluation paused and data_enrichments includes a DocV request (enrichment_provider = "SocureDocRequest")

Verification types

Handle One-Time Passcode

When a One-Time Passcode challenge is triggered, your application must:

1. Display a 6-digit One-Time Passcode input form.
2. Allow the user to retry the code if needed (up to five attempts).
3. Submit the code using PATCH /api/evaluation/{eval_id}.
4. Route the user based on the updated evaluation response.

If the maximum number of attempts is reached, the evaluation will fail and return a REJECT decision.

For more information on One-Time Passcode scenarios, see the One-Time Passcode Integration Guide.

Verify the One-Time Passcode (PATCH)

When the user enters the 6-digit code, your backend should verify it by making a PATCH request to the Evaluation endpoint with the mandatory fields.

Example request

curl -X PATCH "https://riskos.sandbox.socure.com/api/evaluation/{eval_id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "workflow": "non_hosted_advanced_pre_fill",
    "id": "f0b3075b-0ae1-4130-9171-88d6c75a982c",
    "timestamp": "2026-02-16T20:02:44.717Z",
    "data": {
      "individual": {
        "otp": {
          "code": "622123"
        }
      }
    }
  }'

individual.otp fields

One-Time Passcode outcomes

After you submit the One-Time Passcode PATCH request, RiskOS™ returns an updated evaluation. Use status, decision, and tags to determine your next step.

👍

Tip:

Use tags such as "OTP Approved", "Prefill Successful", and "OTP Triggered" to guide your flow.

{
    "eval_id": "8d455113-94f8-4bc2-82f6-e016e078f5dc",
    "decision": "ACCEPT",
    "status": "CLOSED",
    "sub_status": "Accept",
    "tags": [
        "OTP Triggered",
        "OTP Approved",
        "Prefill Successful",
        "Approved to Display the Prefill Data",
        "Additional PII Requested"
    ]
}

{
    "eval_id": "8d455113-94f8-4bc2-82f6-e016e078f5dc",
    "decision": "REVIEW",
    "status": "ON_HOLD",
    "sub_status": "More information needed",
    "tags": [
        "OTP Triggered",
        "OTP Approved",
        "Prefill Successful",
        "Approved to Display the Prefill Data",
        "Additional PII Requested"
    ]
}

{
    "eval_id": "8d455113-94f8-4bc2-82f6-e016e078f5dc",
    "decision": "REJECT",
    "status": "CLOSED",
    "tags": [
        "Phone - High Risk"
    ]
}

Submit identity data

Submit identity data to continue the evaluation after:

• One-Time Passcode verification succeeds, or
• Prefill data is displayed, or
• The workflow requests additional PII

If Prefill data is returned, do not allow users to edit:

• phone_number
• date_of_birth

Handle Additional Identity Data

When additional identity data is required:

• sub_status = More information needed
• tags include Additional PII Requested

What to do

1. Display full onboarding form.
2. Collect identity data.
3. Submit the data using PATCH /api/evaluation/{eval_id}.
4. Continue evaluation

Handle Predictive Document Verification

When an evaluation pauses, RiskOS™ is waiting for physical evidence (ID and selfie) to finalize a decision.

Detect the Predictive Document Verification step-up

Look for:

• Status: eval_status is "evaluation_paused" (or status is "ON_HOLD").
• Provider: data_enrichments contains an entry where enrichment_provider is "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/..."
        }
      }
    }
  ]
}

Complete the handoff

If a token is present, your backend should:

1. Persist the eval_id and token for later correlation with the webhook result.
2. Send token to frontend.
3. Transition the user to the identity verification UI to launch the SDK.

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

<html>
  <head>
    <script src="https://websdk.socure.com/bundle.js"></script>
  </head>
  <body>
    <button onclick="start()">Start Verification</button>
    <div id="websdk"></div>

    <script>
      var config = {
        onProgress: function (event) {
          /* Called during capture */
        },
        onSuccess: function (response) {
          /* Called on success */
        },
        onError: function (error) {
          /* Called on error */
        },
        qrCodeNeeded: true, // Show QR code option
        disableSmsInput: false, // Enable SMS input
        closeCaptureWindowOnComplete: true, // Auto-close tab after document upload confirmation
        autoOpenTabOnMobile: true, // Skip "Continue on New Tab" screen on mobile and launch Capture App in a new tab
      };
      function start() {
        SocureDocVSDK.launch(
          'SDKKey', // Replace with your SDK Key
          'docvTransactionToken', // Replace with the docvTransactionToken
          '#websdk',
          config // optional
        );
      }
    </script>
  </body>
</html>

When the user clicks Start ID Verification, the Capture App launches inside #websdk.

Depending on your integration workflow, the user can access the Capture App using:

1. QR code (desktop → mobile handoff)
2. Secure SMS link (desktop or mobile)
3. Mobile redirect URL (if you choose to redirect directly 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).

📘

iOS and Android apps:

You can launch the Capture App by redirecting the user to the DocV URL returned in the Evaluation response.

data_enrichments[n].response.data.url

If you include data.individual.docv.config.redirect.url in your Evaluation request, the user will be redirected back to your app after capture completes. See the integration guides for iOS Webview or Android Webview for advanced SDK configuration and mobile patterns.

Receive the final decision (Webhook)

After the Capture App flow completes, RiskOS™ resumes the paused evaluation asynchronously. The final result is delivered via a webhook event.

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

Final decision

DocV is asynchronous.

• Wait for updated evaluation or webhook.
• Route based on final decision.

Key rules

• Treat One-Time Passcode and DocV as separate flows.
• Persist eval_id across all steps.
• Do not resubmit DocV.
• Route using decision, sub_status, and tags.

Summary

• Detect the verification type.
• Collect required input.
• Continue with PATCH or DocV SDK.
• Wait for final decision.