Process DocV with Socure Pass Results in Hosted Flow

Evaluation flow

After creating the evaluation and redirecting the user to the Hosted Flow, RiskOS™ manages the verification experience — authenticating returning users via Socure Pass, collecting consent, and guiding new users through Document Verification. The evaluation_completed webhook contains the final, authoritative decision.

1. Returning user (valid Socure Pass)

If the user has a valid, non-expired Socure Pass, they authenticate using their passkey and consent to share previously verified identity data.

No document scan or selfie is required. The evaluation completes using the reused data.

2. New user (first-time verification)

If the user does not have a Socure Pass, they complete standard Document Verification.

The hosted flow renders the Capture App, where the user:

• Scans their ID
• Captures a selfie
• Completes liveness checks

After a successful verification, the user may be enrolled in Socure Pass for future reuse.

3. Returning user (re-verification required)

If the user has a Socure Pass but their document is expired or no longer valid, they must complete Document Verification again.

This follows the same Capture App flow as a new user. After a successful verification, the system updates their Socure Pass with the new document.

Receive the final decision (webhook)

After the Hosted Flow completes, RiskOS™ sends an evaluation_completed webhook to your configured webhook endpoint.

The final outcome is in:

• data.decision

📘

Important:

The webhook payload differs depending on which path the user takes. If the user selects "Verify with Socure Pass," the enrichment comes from the SocurePass provider. If the user selects "Continue with Standard Verification," the enrichment comes from the standard Document Verification provider. Your integration must handle both response shapes.

Socure Pass reuse example webhook (truncated)Standard Document Verification example webhook (truncated)

{
  "event_type": "evaluation_completed",
  "event_id": "3b31289c-2d4a-4107-80bc-dda63031d5a0",
  "data": {
    "eval_id": "2b74fe41-bf69-484a-82c7-4630f5846fa6",
    "decision": "ACCEPT",
    "status": "CLOSED",
    "tags": [
      "Socure Pass Triggered",
      "Socure Pass Has Data",
      "DocV Accept"
    ],
    "data_enrichments": [
      {
        "enrichment_provider": "SocurePass",
        "response": {
          "individual": {
            "given_name": "Jane",
            "family_name": "Doe",
            "date_of_birth": "2000-05-01"
          }
        }
      }
    ]
  }
}

{
  "event_type": "evaluation_completed",
  "event_id": "a4c92f1e-8b3d-4a17-9c5e-f2d8e7b61a03",
  "data": {
    "eval_id": "11111111-2222-3333-4444-555555555555",
    "decision": "ACCEPT",
    "status": "CLOSED",
    "tags": [
      "Document Verification Triggered",
      "DocV Accept"
    ],
    "data_enrichments": [
      {
        "enrichment_provider": "SocureDocRequest",
        "response": {
          "referenceId": "ed6a5077-b272-4a75-8c21-b284e10927cd",
          "status": "SESSION_COMPLETE"
        }
      },
      {
        "enrichment_provider": "Socure",
        "response": {
          "documentVerification": {
            "decision": {
              "value": "accept"
            },
            "reasonCodes": [
              "I831",
              "I836"
            ],
            "documentData": {
              "firstName": "Jane",
              "surName": "Doe",
              "dob": "2000-05-01"
            }
          }
        }
      }
    ]
  }
}

Route the user based on the final decision

Because the evaluation completes asynchronously, your frontend should wait for your backend to persist the final decision before routing the user.

Expose the persisted decision from your backend to the frontend (for example, via a status endpoint), then handle routing as follows:

• ACCEPT → Continue onboarding
• REJECT → Route to your fallback, manual review, or decline flow

One common approach is polling your backend until the stored decision is available.

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

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

📘

Note:

Do not rely on status or eval_status for routing decisions. Use data.decision as the primary field.

Identify the verification path

Determine how the user was verified by checking tags or data_enrichments[].enrichment_provider.

Socure Pass (reuse)

How to identify:

• tags contains "Socure Pass Triggered"
• data_enrichments[].enrichment_provider = "SocurePass"

Verified data location:

• data_enrichments[].response.individual

Standard Document Verification

How to identify:

• tags contains "Document Verification Triggered"
• data_enrichments[].enrichment_provider = "Socure" or "SocureDocRequest"

Verified data location:

• data_enrichments[].response.documentVerification.documentData

Review enrichment results

Use the data_enrichments array to access verified data returned from the completed verification path.

Socure Pass data

• response.individual — Verified identity data returned from Socure Pass reuse

Document Verification data

• response.documentVerification.decision.value — DocV result (accept, reject, resubmit, review)
• response.documentVerification.reasonCodes — Reason codes explaining the result
• response.documentVerification.documentData — Parsed identity data from the document (when available)

Session metadata (DocV only)

• enrichment_provider = "SocureDocRequest"
• response.referenceId — DocV session identifier
• response.status — Session status (for example, SESSION_COMPLETE)

📘

Note:

Socure manages the Hosted Flow verification experience. Your integration only needs to:

• Use the final decision for routing
• Identify which path completed
• Persist any verified data required by your application

Store required data

Persist these fields for tracking and reconciliation:

Key takeaways

• Socure manages the Hosted Flow verification experience.
• Wait for the evaluation_completed webhook before routing the user.
• Use data.decision as the primary routing field.
• Use tags and enrichment_provider to identify whether the user completed Socure Pass reuse or standard Document Verification.
• Handle both Socure Pass and standard Document Verification response shapes.
• To retry a failed or expired verification, create a new evaluation.