Selfie Reverification Setup

How it works

1. Input → You call the Evaluation API with PII and optional DocV config.
2. Document Request → Workflow pauses and returns a URL / QR / token (or sends SMS if enabled) for user handoff to the DocV Capture App.
3. Document Verification → After the user completes required image capture, the workflow resumes, verifies 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 → Route based on DocV decision, reason codes, document type, etc.
6. Decision → 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 session expires.

Workflow components

Step details

1. Input

• What you send:
  • User PII (recommended): data.individual
    • Why include PII: PII is required for extraction matching; extracted documentData will be compared to input PII for added verification confidence.
  • DocV Config (optional)data.individual.docv.config
    • Common config: language (defaults to en-us), send_message, redirect, document_type, use_case_key.
• Docs: See API Integration: Evaluation for full documentation on required fields, available config options, request samples, etc.

2. Document Request (workflow pauses)

• Returns handoff artifacts to launch the Capture App:
  • url, qrCode, docvTransactionToken to provide a handoff to the user to the DocV Capture App
  • If send_message: true and phone_number present → SMS is sent automatically to the user.
• State: status: ON_HOLD, eval_status: evaluation_paused.
• Observe progress: subscribe to DocV event webhooks (case notes) like front/back/selfie uploaded, documents uploaded, session complete.
• Note: If multiple DocV flows are configured on your account, there will typically be an enrichment step for each flow (i.e. Socure Document Request - Default Flow, Socure Document Request - No Selfie).

📘

Paused for user action (required)

The workflow remains on hold until the end user opens the link/QR/SMS and completes capture in the Capture App. Once the capture session finishes (or expires), RiskOS automatically advances to Document Verification. Be sure to surface the handoff URL/QR to the user or enable send_message so they can proceed.

3. Document Verification

• Document Verification is performed on the user captured images.
• Produces DocV decision (accept, review, resubmit, reject).
• Includes reasonCodes, documentType, documentData (extracted fields), and Digital Intelligence (device/network).
• Use these fields in Conditional Decision Logic for final decisioning.

4. Image Request (recommended)

• Retrieves and attaches images to the evaluation so reviewers can view them in the RiskOS dashboard; also enables the ZIP download API.
• Images may be unavailable in some compliant scenarios (e.g., military IDs, minors, retention/deletion rules). If this is the case, this step will produce an error but the workflow will continue as expected.

5. Conditional Decision Logic

• Recommended rule: use documentVerification.decision.value to branch to accept / reject / resubmit / review.
• Common extensions:
  • Route by country or documentType.
  • Use reasonCodes to request targeted resubmits (e.g., glare/blur) or to escalate to review.
• Docs: See the RiskOS™ Dashboard for how to configure the DocV decision and recommendations for adding common custom logic (accepted countries, ID types, etc.)

6. Decision

• Emit the final outcome for the evaluation: accept, reject, resubmit, review, or cancel.

Error handling

In some scenarios, errors may occur for the Document Request and Document Verification enrichment steps.

• Error handling needs to be considered for configuration in the workflow. Errors can be in either of the below fields:
  • socure_docv_error is set
  • socure_doc_request_error is set
• Some common configurations include:
  • On error, route to resubmit and include integration logic to initiate a new evaluation request
  • On error, route to cancel and include integration logic to troubleshoot and initiate a new evaluation request
  • It is recommended to tag the case (e.g., docv_error, docv_request_error, docv_verification_error) for filtering/reporting.

Resubmit handling

• When DocV or configured workflow logic return a resubmit decision, this typically means that there is an issue with the captured images preventing verification to be performed. This decision is reserved for images that do not pass verification, but are not necessarily displaying indications of fraud (quality issues, disallowed ID type). It is recommended to start a new evaluation for these scenarios in which the user would be provided a new DocV transaction to reattempt capturing their images.
• Recommendations:
  • Tailor the user messaging based on the retruned reasonCodes (e.g., use a different ID type, retake in brighter light).
  • Limit the number of retry attempts to reduce endless loops for users.
• For streamlined re-attempt flows or policy nuances, contact your Solutions Consultant team.

Helpful links