Integration Guide

Learn how to integrate Document Verification (DocV) + Watchlist in RiskOS™. This guide walks through generating an evaluation, embedding the Capture App, and handling final onboarding decisions.

Start building

Before you start

Before you begin your implementation, ensure you have the following ready:

Postman Collection

The following Postman collection can be used to test the Document Verification (DocV) + Watchlist solution with the Evaluation endpoint.

Integration flow

This integration enables you to verify users are real people using a government-issued ID scan, a selfie, and automated sanctions screening.

• Government ID + selfie verification: Users complete a secure document capture flow to validate their identity
• Fraud detection: Catch fake IDs, deepfakes, and stolen documents
• Automated sanctions screening: Screen verified identities against global watchlists
• Global coverage: Accept government-issued IDs from 195+ countries

sequenceDiagram
    autonumber
    participant User as End User
    participant App as Your Platform
    participant Socure as Socure

    User->>App: Attempt action to trigger DocV
    App->>Socure: POST /api/evaluation with PII and DocV settings
    Socure-->>App: Respond w/ transaction token
    App-->>User: Show Web SDK to prompt document capture
    
    User->>Socure: Submit document images and selfie to Socure
    
    activate Socure
    Note over Socure: Process submission, run document verification & watchlist screening
    Socure-->>App: Final decision (APPROVE / REJECT)
    deactivate Socure

    App-->>User: Show Onboarding Result

How it works

1. Set up your environment

   Before integrating, configure your backend environment to handle secure REST API requests. Your server is responsible for all communication with RiskOS™ to ensure your SOCURE_API_KEY is never exposed to the client.

   
   

   Integration architecture

   • Backend: Communicates with RiskOS™ via REST API (cURL) using your secret API Key.
   • Frontend: Collects user Identity data (PII) while simultaneously generating device risk telemetry through the Digital Intelligence SDK and the Predictive DocV SDK.
   • Security: All identity data processing must happen server-to-server.

   
   

   Configure your keys

   Retrieve your credentials from the Developer Workbench.

   
   

   Key	Format	Purpose
   API key	Bearer <key>	Secret. Used in server-side cURL headers for authentication.
   SDK key	String	Public. Used in your frontend to initialize the Digital Intelligence and DocV SDKs.
   Workflow name	String	Configuration. The unique ID from the Workflows page in RiskOS™. Must be included in the "workflow" field of your API request payload.

   
   

   Set environment variables

   Store these variables securely on your server. Always use the Sandbox URL for testing.

   
   

   Bash

   # Server-side Environment Variables
   SOCURE_API_KEY="your_api_key_here"
   SOCURE_BASE_URL="https://riskos.sandbox.socure.com"
   SOCURE_WORKFLOW_NAME="your_workflow_name_here"

2. Set up the Digital Intelligence session token

   Before submitting an evaluation, generate a device-specific di_session_token. This short-lived token helps verify device integrity and is required for certain RiskOS™ evaluations.

   
   

   1. Install the Digital Intelligence SDK

   Add the Digital Intelligence Web SDK to your project using npm:

   
   

   Bash

   npm install --save @socure-inc/device-risk-sdk

   
   

   2. Initialize the SDK once per session

   Mount the SocureInit component in a high-level file (such as layout.tsx) to initialize the SDK once per session. This prevents redundant re-initialization during navigation.

   
   

   JSX

   "use client";
   
   import { useEffect, useRef } from "react";
   import { SigmaDeviceManager, SigmaDeviceOptions } from "@socure-inc/device-risk-sdk";
   
   export function SocureInit() {
     const initializedRef = useRef(false);
   
     useEffect(() => {
       if (initializedRef.current) return;
       const sdkKey = process.env.NEXT_PUBLIC_SOCURE_SDK_KEY;
   
       if (sdkKey) {
         SigmaDeviceManager.initialize({ sdkKey } as SigmaDeviceOptions);
         initializedRef.current = true;
       }
     }, []);
   
     return null;
   }

   
   

   3. Generate a session token

   Immediately before submitting a form to your backend, call getSessionToken(). Include the resulting string in your API request payload as the di_session_token field.

   
   

   tsx

   // Call this inside your form submission handler
   export async function getSessionToken() {
     return SigmaDeviceManager.getSessionToken();
   }

3. Retrieve and verify identity data

   Use the DocV & Watchlist workflow to retrieve verified PII while minimizing user friction. This workflow is asynchronous.

   
   

   1. Collect required input

   Your application must collect the following minimum required fields before initiating the workflow:

   
   

   • given_name
   • family_name
   • phone_number
   • address.country

   
   

   Tip: Adding additional personally identifiable information (PII) can improve match accuracy.

   
   

   2. Create an evaluation (POST)

   Send a POST request to the Evaluation endpoint using the DocV & Watchlist workflow. This initiates the identity lookup.

   
   

   • Endpoint:POST /api/evaluation

   
   

   cURL

   curl --location --request POST 'https://riskos.sandbox.socure.com/api/evaluation' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer YOUR_API_KEY' \
   --data-raw '{
       "id": "APP-123456",
       "timestamp": "2025-07-31T15:00:10.761Z",
       "workflow": "docv_watchlist",
       "data": {
           "individual": {
               "given_name": "John",
               "family_name": "Smith",
               "date_of_birth": "1989-05-07",
               "phone_number": "+19998887777",
               "address": {
                   "line_1": "1234 N College Ave",
                   "locality": "New York City",
                   "major_admin_division": "NY",
                   "country": "US",
                   "postal_code": "10001"
               },
               "docv": {
                   "config": {
                       "document_type": "license",
                       "send_message": true,
                       "language": "en-us",
                       "redirect": {
                           "method": "POST",
                           "url": "https://example.com/docv"
                       }
                   }
               },
               "di_session_token": "eyJraWQiOi_di_token"
           }
       }
   }'        

   
   

   Top-level fields

   Field	Type	Required	Description	Example
   id	String	Required	Required. Customer-defined unique identifier for the request. This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run and can impact processing behavior, results, and downstream workflows.	"fb428165-6a1c-4d36-afbc-c8a946c1287d"
   timestamp	String <Date-Time>	Required	RFC 3339 timestamp indicating when the evaluation request was initiated by your system.	"2026-02-17T14:22:06.628Z"
   workflow	String	Required	Your environment-specific workflow identifier. You can find this value in the RiskOS™ Dashboard > Developer Workbench > Integration Checklist.	"KYC & Watchlist Screening: Direct API Integration"
   data	Object	Required	Main payload containing consumer information, device data, and event details for evaluation.
   → individual	Object	Required	Primary identity object containing individual's information.	See individual schema below.

   
   

   individual fields

   Including as much personally identifiable information (PII) as possible is strongly encouraged. Providing PII supports consent audits and consumer data requests, and it also improves match accuracy and overall verification performance.

   Field	Type	Required	Description	Example
   given_name	String	Required	First name	"John"
   family_name	String	Required	Last name	"Smith"
   date_of_birth	String	Required	Date of birth (YYYY-MM-DD)	"1989-05-07"
   phone_number	String	Required	Phone number in E.164 format	"+19998887777"
   address	Object	Required	Consumer address	See address schema below.
   docv	Object	Conditional	DocV configuration and capture settings	See docv schema below.

   
   

   address fields

   Field	Type	Required	Description	Example
   line_1	String	Optional	Street address line 1	"1234 N College Ave"
   line_2	String	Optional	Street address line 2	"Apt 3C"
   locality	String	Optional	City	"New York City"
   major_admin_division	String	Optional	State/province or region (ISO 3166-2)	"NY"
   postal_code	String	Optional	ZIP or postal code	"10001"
   country	String	Required	ISO 3166-1 alpha-2 country code	"US"

   
   

   docv fields

   Use the fields in the table below to configure Predictive DocV in your workflow.

   Field	Type	Required	Description	Example
   config	Object	Optional	Configuration options controlling Capture App behavior and document verification flow for a given transaction.	See config schema below.
   → send_message	Boolean	Optional	Set to true to send an SMS to the provided phone number with the document request URL. Defaults to false. - US & Canada: sent from short code 33436 - Other countries: sent from +1 (510) 330-19xx	true
   → language	String	Optional	Determines Capture App UI language. Defaults to en-us.	"en-us"
   → use_case_key	String	Optional	Deploys a specific Capture App flow created in RiskOS™. Defaults to the account’s default flow or the flow configured in the RiskOS™ workflow.	"default_capture_flow"
   → redirect	Object	Optional	Object containing post-capture redirect behavior.	See redirect schema below.
   → redirect.method	String	Conditional	Required if redirect is provided. Accepts GET or POST.	"POST"
   → redirect.url	String	Conditional	Required if redirect is provided. The destination URL to send the consumer after capture. Can include query strings for transaction tracking.	"https://example.com/docv"
   → document_type	String	Optional	Restrict to a single document type (license or passport) for a simplified flow. Users skip the document type selection screen when passed.	"license"

4. Handling Step-Up: Triggering Document Verification

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

   
   

   1. Detect the Pause

   Identify a Step-Up trigger by monitoring for these specific values in the API response:

   • Status: eval_status is "evaluation_paused" (or status is "ON_HOLD").
   • Provider: data_enrichments contains an entry where enrichment_provider is "SocureDocRequest".

   
   

   2. Extract Handoff Assets

   Locate the SocureDocRequest object and extract the following from response.data:

   
   

   Field	Purpose
   docvTransactionToken	Required. Pass this to your frontend to initialize the DocV SDK.
   url	Optional. Use for direct mobile redirects to the Capture App.
   qrCode	Optional. Base64 PNG for desktop-to-mobile handoff.

   
   

   Example response (truncated)

   {
     "eval_id": "500c6b88-9f5c-4d62-9422-163a59a343fe",
     "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/#/dv/70c6a4bc-f646-4c6a-94c1-9cd428e356ef"
           }
         }
       }
     ]
   }

   
   

   3. 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. Return the token to your client-side application.
   3. Transition the user to the identity verification UI to launch the SDK.

   
   

   Response schema

   Top-level fields

   Field	Type	Description	Example
   id	String	Your original request id, echoed back in the response.	"DOCV-CASE-001234"
   eval_id	String (UUID)	Internally generated for each evaluation; required for GET/PATCH requests.	"e5c3b4b2-9e0f-44f2-9c6f-0a3a5f2b7b61"
   decision	String	Final decision — PASS, REVIEW, or FAIL.	"REVIEW"
   status	String	Case status in RiskOS™ — OPEN, CLOSED, or ON_HOLD.	"ON_HOLD"
   eval_status	String	Processing state — evaluation_paused indicates Step-Up is required.	"evaluation_paused"
   tags	Array	Labels explaining the decision (e.g., "Document Verification Triggered").	["Document Verification Triggered"]

   
   

   data_enrichments fields

   Field	Type	Description	Example
   enrichment_name	String	Name of the enrichment product.	"Socure DocV"
   enrichment_provider	String	Provider identifier. Look for SocureDocRequest.	"SocureDocRequest"
   status_code	Integer	HTTP status code of the enrichment call.	200
   response	Object	Payload containing the DocV handoff assets.	See response schema

   
   

   response.data Handoff Details

   Field	Type	Description
   docvTransactionToken	String	Required to initialize the DocV Web SDK.
   url	String	Direct link to the Socure-hosted Capture App.
   qrCode	String	Base64-encoded PNG for desktop-to-mobile handoff.

5. Integrate with the DocV 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.

   
   
   

   Quick start

   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

   <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:

   
   

   • QR code (desktop → mobile handoff)
   • Secure SMS link (desktop or mobile)
   • 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).

6. 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.

   
   

   Listen for the evaluation_completed event

   RiskOS™ sends an evaluation_completed event when processing finishes. The final outcome is in data.decision.

   
   

   Example webhook payload (truncated)

   {
   "event_type": "evaluation_completed",
   "event_id": "3b31289c-2d4a-4107-80bc-dda63031d5a0",
   "event_at": "2025-07-17T01:20:01Z",
   "data": {
       "eval_id": "11111111-2222-3333-4444-555555555555",
       "id": "client-transaction-12345",
       "workflow": "consumer_onboarding",
       "workflow_id": "5937a624-f298-452c-9169-ceeae9e66b74",
       "workflow_version": "1.0.0",
       "environment_name": "Sandbox",
       "eval_source": "API",
       "eval_start_time": "2025-07-17T01:18:27Z",
       "eval_end_time": "2025-07-17T01:20:01Z",
       "eval_status": "evaluation_completed",
       "decision": "ACCEPT",
       "decision_at": "2025-07-17T01:20:01Z",
       "status": "CLOSED",
       "sub_status": "Accept",
       "tags": [],
       "notes": "",
       "review_queues": [
       "Default Queue"
       ],
       "data_enrichments": [
       {
           "enrichment_name": "Socure Document Request - Default Flow",
           "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/request",
           "enrichment_provider": "SocureDocRequest",
           "status_code": 200,
           "response": {
           "referenceId": "ed6a5077-b272-4a75-8c21-b284e10927cd",
           "status": "SESSION_COMPLETE",
           "data": {
               "docvTransactionToken": "7d6ad42b-f804-4255-b25e-268b8a77c86f",
               "url": "https://verify.socure.com/#/dv/7d6ad42b-f804-4255-b25e-268b8a77c86f"
           }
           }
       },
       {
           "enrichment_name": "Socure Document Verification",
           "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/verify",
           "enrichment_provider": "Socure",
           "status_code": 200,
           "response": {
           "referenceId": "ed6a5077-b272-4a75-8c21-b284e10927c",
           "documentVerification": {
               "decision": {
               "name": "standard",
               "value": "accept"
               },
               "reasonCodes": [
               "I831",
               "I836"
               ],
               "documentType": {
               "type": "Drivers License",
               "country": "USA",
               "state": "NY"
               },
               "documentData": {
               "firstName": "Test",
               "surName": "User",
               "fullName": "Test User",
               "dob": "1990-01-01",
               "documentNumber": "TST1234567",
               "expirationDate": "2030-01-01"
               },
               "digitalIntelligence": {
               "device": {
                   "id": "e92ee549-e3c7-4307-9be7-32fefb0db9a4",
                   "globalDeviceId": "aecddd42-f223-3333-940c-87baab4c6645",
                   "sessionCreatedAt": "2025-07-17T01:18:28Z",
                   "deviceCaptureAt": "2025-07-17T01:18:45Z",
                   "computed": {
                   "statisticalId": "b90c8faddcd15cd5eafc09bfe4e460d557c5e516f8c5b44b8d3ec1e6f60c30f8",
                   "isVirtualMachine": false,
                   "sessionAgeMinutes": 45
                   },
                   "network": {
                   "connectionIp": "203.0.113.10",
                   "webRtcPublicIp": "203.0.113.10",
                   "webRtcInternalIp": "10.0.0.15",
                   "realIp": "203.0.113.10",
                   "isTor": false,
                   "isProxy": false,
                   "isVpn": false,
                   "isConsumerPrivacy": false,
                   "isRiskyNetwork": false,
                   "isp": "Example ISP",
                   "ispType": "home",
                   "asn": 64500,
                   "asnName": "EXAMPLE-NET",
                   "domainName": "example.net",
                   "org": "Example Org",
                   "isMobileCarrier": false,
                   "speed": "broadband",
                   "networkLocation": {
                       "countryCode": "US",
                       "region": "NY",
                       "city": "New York",
                       "postalCode": "10001",
                       "latitude": 40.75,
                       "longitude": -73.99,
                       "metroCode": 501,
                       "continentCode": "NA",
                       "timezoneName": "America/New_York",
                       "gmtOffset": "-0500"
                   }
                   }
               }
               }
           }
           }
       }
       ]
   }
   }

   
   

   Key response fields

   RiskOS™ returns a consistent set of top-level fields that describe the outcome of an evaluation, along with enrichment-specific results that depend on your workflow configuration.

   
   

   Where to find specific results

   Area	Fields	How to use it
   Decision and routing	decision, decision_at, tags, review_queues, notes, score	Primary control signals. Branch application logic using decision. Use tags, queues, notes, and score for secondary routing, review, and explanation.
   Module results	Module-specific fields (for example: reasonCodes, scores, extracted attributes)	Evidence and signals produced by workflow modules. Use for escalation, compliance review, investigation, and audit.
   Identifiers and traceability	id, eval_id	Persist these identifiers to correlate API calls, logs, webhooks, GET requests, and support cases.
   Enrichment execution	data_enrichments[] (response, status_code, total_attempts, is_source_cache)	Inspect enrichment outputs and detect provisioning issues, partial failures, retries, or cached responses.
   Workflow context	workflow, workflow_id, workflow_version	Understand which workflow ran and which version produced the result. Useful for debugging and historical analysis.
   Evaluation lifecycle	eval_status, status, sub_status	Execution and case state only. Useful for monitoring and asynchronous workflows. Do not use for business decisions.
   Execution context	eval_source, eval_start_time, eval_end_time, environment_name	Observability and performance metadata for latency tracking, environment validation, and API vs Dashboard attribution.

   
   

   Decision and routing (primary control signals)

   Use these fields to determine what action your application should take.

   decision values are workflow-specific and may differ from the examples shown in this guide.

   Field	Type	Description	Example
   decision	String (enum)	Final evaluation result. Possible values: • ACCEPT • REVIEW • REJECT Note: The fields returned can be customized to fit your integration or business needs.	"REVIEW"
   decision_at	String <Date-Time>	RFC 3339 timestamp when the decision was finalized.	"2025-10-18T14:09:22.641Z"
   score	Number	If configured for a workflow, provides an aggregate score of all steps. This can be used for risk banding, additional routing, or analytics alongside the primary decision value.	0.63
   tags	Array of Strings	Array of labels applied during the workflow to highlight routing choices, notable signals, or rule outcomes. Useful for reporting, segmentation, or UI highlighting in the RiskOS™ Dashboard.	[]
   review_queues	Array of Strings	Lists any manual review queues the evaluation was sent to. Empty when the case is fully auto-resolved without human review.	[]
   notes	String	Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context.	"Manual review recommended based on risk signals"

   
   

   Evaluation lifecycle and status

   These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.

   Field	Type	Description	Example
   eval_status	String (enum)	Indicates the current state of an evaluation in RiskOS™. Possible values: • evaluation_completed • evaluation_paused • evaluation_in_progress	"evaluation_completed"
   status	String (enum)	Indicates the current state of an evaluation or case. Possible values: • OPEN • CLOSED	"CLOSED"
   sub_status	String	Provides additional detail about the evaluation status. Example values: • Under Review • Pending Verification • Accept • Reject	"Under Review"

   
   

   Identifiers and traceability

   Use these fields to correlate requests, logs, webhooks, and support cases.

   Field	Type	Description	Example
   id	String (UUID or custom string)	Your evaluation identifier within RiskOS™. Note: This is customer-generated.	"APP-123456"
   eval_id	String (UUID)	RiskOS-generated unique identifier for the evaluation.	"6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816"
   workflow_id	String (UUID)	Unique identifier for the workflow run.	"dc7f261e-b158-477e-9770-7e4eae066156"
   workflow_version	String	Version of the executed workflow.	"28.16.0"

   
   

   Execution context

   These fields provide timing and environment context for the evaluation.

   Field	Type	Description	Example
   eval_source	String enum	Indicates where the evaluation was initiated from. Possible values: • API: Request submitted via the Evaluation API. • Dashboard: Case created or evaluated through the RiskOS™ Dashboard.	"API"
   eval_start_time	String <Date-Time>	RFC 3339 timestamp for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring.	"2025-10-07T23:50:03.60187976Z"
   eval_end_time	String <Date-Time>	RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. Can be paired with eval_start_time to compute total processing time.	"2025-10-07T23:50:03.738794253Z"
   environment_name	String	Indicates which environment the evaluation ran in. Typically Sandbox for testing or Production for live traffic.	"Sandbox"

   
   

   Enrichment results

   Enrichment outputs are returned in the data_enrichments array.

   Field	Type	Description	Example
   enrichment_name	String	Name of the enrichment executed as part of the evaluation.	"Socure DocV"
   enrichment_endpoint	String	API endpoint used for the enrichment request.	"https://sandbox.dev.socure.com /api/3.0/DocumentVerification"
   enrichment_provider	String	Provider responsible for the enrichment.	"Socure"
   status_code	Integer	HTTP status code returned by the enrichment provider.	200
   request	Object	Payload sent to the enrichment provider (often redacted in documentation examples).	{ ... }
   response	Object	Enrichment response payload containing DocV results.	See documentVerification response schema below.

   
   

   documentVerification fields

   Field	Type	Description	Example
   reasonCodes	Array of Strings	List of rule or insight codes returned from DocV analysis.	["I834","I823","I826","I845","I820"]
   documentType	Object	Details about the document type provided for verification.	See documentType fields
   decision	Object	Result of the document verification analysis.	See decision fields
   documentData	Object	Parsed data extracted from the submitted document.	See documentData fields

   
   

   reasonCodes are machine-readable flags that explain why a decision occurred (e.g., data mismatches, capture issues, authenticity checks). They appear under the DocV enrichment response and are intended for routing, UX, and review workflows.

   
   

   Where you’ll see them

   • data_enrichments.response.documentVerification.reasonCodes

   
   

   How to use them

   • Drive resubmission UX (e.g., prompt for glare removal if an image quality code is present).
   • Route to manual review when authenticity or data consistency codes indicate risk.
   • Log for audit and analytics.

   The full catalog of reason codes and their descriptions is available in your Socure documentation/console or in the reason code list in the RiskOS™ Dashboard.

   
   

   documentType

   Field	Type	Description	Example
   type	String	Human-readable document type.	"Drivers License"
   country	String	Country associated with the document type.	"USA"
   state	String	State/region associated with the document type.	"NY"

   
   

   Supported document types

   Below are the document types you may encounter in documentVerification.documentType and when configuring capture flows. Coverage and acceptance may vary by country and program.

   Document Type	Description
   Drivers License	A government-issued license permitting the consumer to operate a motor vehicle.
   Identification Card	A non-driver government-issued photo ID for verifying identity.
   Passport	An official government document certifying identity and nationality, used for international travel.
   Employment Authorization Card	A document issued by USCIS that proves authorization to work in the U.S.
   Permanent Resident Card	A document (e.g., U.S. Green Card) proving the consumer’s lawful permanent resident status.
   Passport Card	A wallet-sized U.S. document used for land and sea travel between certain countries.
   Military ID	An ID card issued by a country’s armed forces to identify active-duty or retired service members.
   Health Card	An ID card issued by a government or insurer to access health services.
   Visa	An official endorsement permitting the consumer to enter, stay, or work in a foreign country.
   Social Security Card	A U.S. government-issued card showing the consumer’s Social Security Number (SSN).
   Weapons License	A document permitting the consumer to carry or own firearms or other regulated weapons.
   Tribal ID Card	A government-recognized identity card issued by a Native American or Indigenous tribe.
   Mexican Permanent Resident Card	An identity document for foreign nationals authorized to live permanently in Mexico.

   
   

   decision

   DocV responses are recommendations only. They are intended to inform your decisioning process and should be integrated into your organization’s broader risk strategy.

   Field	Type	Description	Example
   name	String	Internal label representing the configured decision rule set (e.g., "lenient" or "strict").	"lenient"
   value	String	Outcome of the DocV analysis. One of: • accept — Images met validation criteria and were verified. • reject — Images failed some or all required validation criteria. • resubmit — User must resubmit due to unacceptable image quality or missing data. • review — Images did not meet configured criteria and should be manually reviewed. Returned only if enabled in your DocV Product Settings.	"reject"

   
   

   documentData

   The documentData object contains the extracted data from OCR, barcode, or MRZ.

   If DocV cannot extract sufficient information due to poor image quality or unreadable fields, the documentData object will not be present, and the decision will be resubmit.

   Field	Type	Description	Example
   personalNumber	String	The personal identifier value extracted from the ID, when applicable. Note: The meaning and availability of this value vary by country and document type, but it generally represents an identifier tied to the individual rather than the document itself (for example, a tax identification number or voter ID).	"123456"
   personalNumberType	String	Indicates what the personal number represents. Supported values depend on the issuing country and document type.	BRA_CPF
   firstName	String	First/given name parsed from the document.	"John"
   surName	String	Last/family name parsed from the document.	"Smith"
   fullName	String	Full name as printed on the document.	"John Smith"
   address	String	Single-line address string (as returned).	"32194 N College Ave, New York City, NY 10001"
   parsedAddress	Object	Structured address parts extracted from address.	See parsedAddress fields
   documentNumber	String	Document identifier/number.	"00000000"
   dob	String	Date of birth (YYYY-MM-DD).	"1989-05-07"
   issueDate	String	Document issue date (YYYY-MM-DD).	"2021-01-12"
   expirationDate	String	Document expiration date (YYYY-MM-DD).	"2029-05-07"
   barcode	Object	Contains identity and license details parsed from the barcode of a government-issued ID.	See barcode fields.

   
   

   parsedAddress fields

   Field	Type	Description	Example
   physicalAddress	String	Primary street address (line 1) of the parsed location.	"32194 N College Ave"
   physicalAddress2	String	Combined city, state, and postal code as returned from parsing.	"New York City NY 10001"
   city	String	City component extracted from the parsed address.	"New York City"
   state	String	State, province, or regional code component extracted from the address.	"NY"
   country	String	ISO 3166-1 alpha-2 country code associated with the parsed address.	"US"
   zip	String	Postal or ZIP code component extracted from the parsed address.	"10001"

   
   

   barcode fields

   Field	Type	Description	Example
   firstName	String	The individual’s given or first name as encoded in the barcode.	"John"
   middleName	String	The individual’s middle name or initial extracted from the barcode.	"Larry"
   surName	String	The individual’s last name or family name as encoded in the barcode.	"Smith"
   nameSuffix	String	Any name suffix present, such as Jr., Sr., II, or III.	"JR"
   complianceType	String	Code representing the license’s compliance type (e.g., Federal or state).	"F"
   licenseClass	String	The class or category of license (e.g., commercial, operator, etc.).	"C"

7. 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, then route the user accordingly.

   
   

   • ACCEPT → Continue onboarding
   • REJECT → Route to fallback or review flow

   
   

   One common approach is polling your API until the stored decision changes.

   
   

   ts

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

---

Final integration validation checklist