Secondary Document Setup

RiskOS™ Setup: Secondary Document Capture

Use this guide to assemble a RiskOS™ workflow for the Secondary Document Capture flow—what steps to add, what each step produces, and how to handle errors and resubmits.

The workflow follows the same shape as a standard Document Verification flow, with the flow-specific differences in the following sections.

What's different for this flow

What the consumer captures: supporting documents such as utility bills, bank statements, or other proof-of-address documents—not a government-issued ID, and no selfie.
Accepted file types: the Capture App accepts JPEG, PNG, and PDF uploads for secondary documents.
No facial match: because no selfie is captured, the workflow produces no facial-comparison signals.
Configure the flow: select the Secondary Document Capture flow server-side through your Capture App flow configuration (config.use_case_key) or workflow setup. See Secondary Document Capture for the consumer experience and Create an Evaluation for request fields.

For the exact enrichment-object schema this flow returns, see the API Reference.

Before You Start

Make sure you have the following:

Access to the RiskOS™ Dashboard with the Predictive DocV enrichment enabled.

Your account owner or administrator can enable this for you. If you're unsure who to contact, contact support for assistance.

A published Capture App flow for your DocV flow type.

A basic understanding of RiskOS™ workflows and enrichment steps.

Execution Flow

Predictive DocV runs as an enrichment step in a RiskOS™ workflow. Because document capture happens on the consumer's device, the workflow pauses at the Document Request step and resumes automatically once capture finishes.

user handoff

Input

Document Request

Capture App

Document Verification

Conditional Decision Logic

Decision

Input — You call the Evaluation API with PII and optional DocV config.
Document Request — The workflow pauses and returns a URL / QR / token (or sends SMS if enabled) for user handoff to the DocV Capture App.
Document Verification — After the consumer completes capture, the workflow resumes, verifies the images, and returns DocV results.
Image Request (optional but recommended) — Retrieves captured images and attaches them to the case in RiskOS™.
Conditional Decision Logic — Routes based on the DocV decision, reason codes, document type, and other signals.
Decision — Emits the final outcome ( accept, reject, resubmit, review, or cancel).

📘

Note:

After Document Request, the workflow stays paused until the end user acts (opens the link/QR/SMS and completes capture) or the Document Request expires. There is no API to “force-continue” — RiskOS™ automatically resumes at Document Verification once capture finishes or the session expires.

Add DocV to a Workflow

In the RiskOS™ Dashboard, go to Workflows and create a new workflow or open an existing one.
On the workflow canvas, select the plus (+) icon.
Add a Document Request enrichment step, then add a Document Verification enrichment step.
(Recommended) Add an Image Request enrichment step to attach captured images to the case.
Add Conditional Decision Logic and a Decision step to route on the DocV outputs.

After the enrichment is added, its outputs are available to all downstream workflow components.

📘

Note:

If your account has multiple DocV flows, there is typically an enrichment step for each flow (for example, Socure Document Request - Default Flow, Socure Document Request - No Selfie).

Required and Optional Inputs

DocV evaluates the consumer information provided through your workflow. Providing complete and accurate inputs improves extraction matching and verification confidence.

Required Inputs

data.individual.given_name — Consumer's first/given name
data.individual.family_name — Consumer's last/family name
data.individual.phone_number — Phone number in E.164 format
data.individual.address.country — Country code in ISO 3166-1 alpha-2 format

Optional Supporting Inputs

When available, include these fields to improve match accuracy and verification confidence:

data.individual.date_of_birth
data.individual.email
data.individual.address.line_1
data.individual.address.locality
data.individual.address.major_admin_division
data.individual.address.postal_code
data.individual.docv.config — Capture App behavior (language, send_message, redirect, document_type, use_case_key)

Omitting optional fields does not prevent execution, but extracted documentData is compared to input PII, so richer inputs strengthen the result.

Workflow Components Used by DocV

Component	Purpose	Typical input	Output
Input	Start an evaluation	PII (name/DOB/address/phone), `docv.config` (language, send_message, etc.)	Evaluation created; workflow begins
Document Request	Create capture session & pause	—	URL / QR Code / `docvTransactionToken` (or SMS sent)
Document Verification	Verify uploaded images	—	DocV decision, reasonCodes, documentData
Image Request (rec.)	Attach images to the case (dashboard + API download)	`referenceId` from DocV response	Images available in RiskOS™ & via download endpoint
Condition	Apply your rules	DocV decision, reason codes, document type/country	Route to final Decision step
Decision	Emit final outcome	Routed value	accept / reject / resubmit / review / cancel

Common Decision Patterns

DocV returns a module decision plus reason codes rather than a numeric risk score. Use documentVerification.decision.value in conditions and decision rules to route evaluations. The following patterns are common starting points — adjust them to match your organization's fraud policy and risk tolerance.

Decision-Based Routing

Condition	Suggested Action	Rationale
`documentVerification.decision.value = accept`	Continue	Document verified — proceed to the next workflow step
`documentVerification.decision.value = review`	REVIEW	Inconclusive signals — route to manual review
`documentVerification.decision.value = resubmit`	Resubmit	Image quality or usability issue — start a new evaluation
`documentVerification.decision.value = reject`	REJECT	Verification failed or fraud signals present

Attribute-Based Routing

Pattern	Suggested Action
Disallowed `documentType` or unsupported issuing country	REJECT or REVIEW
Reason codes indicate glare, blur, or low image quality	Resubmit
Expired document or consumer under your minimum age	REJECT per policy
Accepted document type and country with a clean `accept` decision	Continue

Error Handling

Errors can occur on the Document Request and Document Verification enrichment steps. Configure error handling in the workflow for these fields:

socure_doc_request_error is set
socure_docv_error is set

Common configurations:

On error, route to resubmit and add integration logic to initiate a new evaluation request.
On error, route to cancel and add integration logic to troubleshoot and initiate a new evaluation request.
Tag the case (for example, docv_error, docv_request_error, docv_verification_error) for filtering and reporting.

Resubmit Handling

A resubmit decision typically means a captured image prevented verification — a quality issue or a disallowed ID type, not necessarily fraud. Start a new evaluation so the consumer receives a fresh DocV transaction to recapture their images.

Recommendations:

Tailor the consumer messaging based on the returned reasonCodes (for example, use a different ID type, retake in brighter light).
Limit the number of retry attempts to avoid endless loops.
For streamlined re-attempt flows or policy nuances, contact your Solutions Consultant team.

Save and Publish

Once your workflow is configured, publish it to go live. After publishing, capture the workflow identifier you pass as workflow on the Evaluation API request.

Workflow Testing Checklist

Use this checklist to confirm accuracy, resilience, and completeness before going live.

PII inputs are collected and passed consistently
Country codes use the ISO 3166-1 alpha-2 format
The Document Request handoff (URL / QR / SMS) is surfaced to the consumer
Workflow routing on the DocV decision aligns with your fraud policy and risk tolerance
Error, resubmit, and review paths are clearly defined
The Image Request step is included so reviewers can view captured images

Related Enrichments

Enrichment	Combination pattern
Selfie Intelligence	Add a live selfie for age, liveness, and trust checks
Selfie Reverification	Re-authenticate a returning consumer against a prior DocV headshot
Secondary Document Capture	Collect supporting documents such as proof of address
Digital Intelligence	Layer device and network signals onto the document decision

Related Concepts

Helpful Links

API Integration \
How to call the Evaluation endpoint, pass DocV configs, and interpret responses.

Webhooks \
Subscribe to DocV progress (case notes) and evaluation completed events.

Retrieve Images \
Attach images to cases and download them via the ZIP endpoint.

Custom Decision Logic \
Use DocV decisions, reason codes, and attributes to drive outcomes.

Updated about 1 month ago