## RiskOS™ Setup: Document Verification

Use this guide to assemble a **RiskOS™** workflow for the **Document Verification** flow, where the consumer captures a government-issued ID and a selfie—what steps to add, what each step produces, and how to handle **errors** and **resubmits**.

## 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](mailto:support@socure.com) for assistance.
- A published [Capture App flow](https://help.socure.com/riskos/docs/capture-app-setup) for your DocV flow type.
- A basic understanding of RiskOS™ [workflows](https://help.socure.com/riskos/docs/workflows) and [enrichment steps](https://help.socure.com/riskos/docs/enrichment).

## Execution Flow

Predictive DocV runs as an [enrichment step](https://help.socure.com/riskos/docs/enrichment) 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
```

1. **Input** — You [call](https://help.socure.com/riskos/reference/postevaluation#/) the **Evaluation** API with PII and optional DocV config.
2. **Document Request** — The workflow **pauses** and returns a **URL / QR / token** (or sends **SMS** if enabled) for user handoff to the [DocV Capture App](https://help.socure.com/riskos/docs/capture-app#/).
3. **Document Verification** — After the consumer completes capture, the workflow **resumes**, verifies the images, and returns DocV results.
4. **Image Request** _(optional but recommended)_ — Retrieves captured images and attaches them to the case in RiskOS™.
5. **Conditional Decision Logic** — Routes based on the DocV decision, reason codes, document type, and other signals.
6. **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

1. In the RiskOS™ Dashboard, go to **Workflows** and create a new workflow or open an existing one.
2. On the workflow canvas, select the **plus (+)** icon.
3. Add a **Document Request** enrichment step, then add a **Document Verification** enrichment step.
4. _(Recommended)_ Add an **Image Request** enrichment step to attach captured images to the case.
5. 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](https://help.socure.com/riskos/docs/input) | Start an evaluation | PII (name/DOB/address/phone), `docv.config` (language, send_message, etc.) | Evaluation created; workflow begins |
| [Document Request](https://help.socure.com/riskos/docs/enrichment) | Create capture session & pause | — | URL / QR Code / `docvTransactionToken` (or SMS sent) |
| [Document Verification](https://help.socure.com/riskos/docs/enrichment) | Verify uploaded images | — | DocV **decision**, **reasonCodes**, **documentData** |
| [Image Request](https://help.socure.com/riskos/docs/enrichment) _(rec.)_ | Attach images to the case (dashboard + API download) | `referenceId` from DocV response | Images available in RiskOS™ & via download endpoint |
| [Condition](https://help.socure.com/riskos/docs/condition) | Apply your rules | DocV decision, reason codes, document type/country | Route to final **Decision** step |
| [Decision](https://help.socure.com/riskos/docs/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](https://help.socure.com/riskos/docs/condition) and [decision rules](https://help.socure.com/riskos/docs/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](https://help.socure.com/riskos/docs/docv-sdk-integration#/)

## 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](https://help.socure.com/riskos/docs/selfie-intelligence#/) | Add a live selfie for age, liveness, and trust checks |
| [Selfie Reverification](https://help.socure.com/riskos/docs/selfie-reverification#/) | Re-authenticate a returning consumer against a prior DocV headshot |
| [Secondary Document Capture](https://help.socure.com/riskos/docs/secondary-documents#/) | Collect supporting documents such as proof of address |
| [Digital Intelligence](https://help.socure.com/riskos/docs/digital-intelligence) | Layer device and network signals onto the document decision |

## Related Concepts

- [Socure Hosted UX (Capture App)](https://help.socure.com/riskos/docs/capture-app)
- [Enrichment Step](https://help.socure.com/riskos/docs/enrichment)
- [Condition Step](https://help.socure.com/riskos/docs/condition)
- [Decision Step](https://help.socure.com/riskos/docs/decision)
- [Configuring Decision Logic](https://help.socure.com/riskos/docs/docv-decision-logic-configuration)