Integration Guide

Hosted flow

This integration allows your platform to:

• Generate a verification session
• Redirect the user to a RiskOS™ hosted onboarding experience
• Receive a final decision asynchronously
• Route the user based on the outcome

Your application does not collect identity data directly. RiskOS™ manages the full verification experience and returns control to your redirect_uri when complete.

How document verification works

If additional verification is required during the hosted flow, RiskOS™ will trigger Predictive Document Verification (DocV).

Users may be asked to:

• Capture a government-issued ID
• Take a biometric selfie
• Complete liveness verification

Final decisions are delivered asynchronously via webhook. You must configure a webhook endpoint to receive evaluation_completed events.

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. Customize the hosted experience

   Add your logo, branding, and customized copy on the Templates tab in the RiskOS™ Dashboard.

2. Generate and launch the Hosted Flow

   Use the Hosted Flow to delegate identity collection, fraud checks, watchlist screening, and optional Document Verification (DocV) to RiskOS™. This workflow is asynchronous.

   
   

   1. Create an evaluation (POST)

   Your server must initiate the hosted workflow by sending a POST request to the Evaluation endpoint. Include your workflow name and a redirect_uri where the user should return after completing the hosted flow.

   
   

   • Endpoint: POST /api/evaluation

   
   

   cURL

   curl --request POST \
   --url "https://riskos.sandbox.socure.com/api/evaluation" \
   --header "Accept: application/json" \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer YOUR_API_KEY" \
   --data '{
       "id": "17e9a02a-a5a7-442b-9b28-2034e1ed9d53",
       "timestamp": "2025-08-14T20:10:04.535Z",
       "workflow": "consumer_onboarding",
       "data": {
           "individual": {     
           "docv": {
               "config": {
                   "send_message": true
               }
           }                    
           "custom": {
               "redirect_uri": "https://yourapp.com/callback"
           }
       }
   }'

   
   

   Request schema

   Field	Type	Required	Description	Example
   id	String (UUID)	Required	Unique identifier for this evaluation request. Must be unique per submission.	17e9a02a-a5a7-442b-9b28-2034e1ed9d53
   timestamp	String (RFC 3339 Date-Time)	Required	Time the evaluation request was initiated by your system.	2025-08-14T20:10:04.535Z
   workflow	String	Required	The Hosted Flow workflow name configured in RiskOS™ (e.g., consumer_onboarding).	consumer_onboarding
   data	Object	Required	Container object for workflow inputs and configuration.	—
   data.custom.redirect_uri	String (URL)	Required	URL where the user will be redirected after completing the Hosted Flow.	https://yourapp.com/callback

   
   

   docv fields

   Use the fields in the table below to configure Predictive DocV behavior within 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"

   
   

   Example response

   The response returns a hosted redirect_uri and an eval_id. The evaluation will return status = ON_HOLD while waiting for user interaction.

   
   

   JSON

   {
       "id": "4e67a341-826c-4813-99b4-6c91cf2de4f7",
       "workflow": "consumer_onboarding",
       "workflow_id": "63e7534e-675e-4e7b-985b-f578d98347d0",
       "workflow_version": "11.71.0",
       "eval_source": "API",
       "eval_id": "1cc8f438-3c65-47ec-a1de-ad828dbcfa25",
       "eval_start_time": "2026-02-17T23:16:06.555204712Z",
       "eval_end_time": "2026-02-17T23:16:06.555902399Z",
       "decision": "REVIEW",
       "decision_at": "2026-02-17T23:16:06.555912097Z",
       "status": "ON_HOLD",
       "sub_status": "More information needed",
       "tags": [],
       "notes": "",
       "review_queues": [
           "Default Queue"
       ],
       "eval_status": "evaluation_paused",
       "environment_name": "Sandbox"
   }

   
   

   Response schema

   The following fields are returned in the Evaluation API response.

   Field	Type	Description	Example
   id	String (UUID or custom string)	Customer-generated identifier supplied in the original POST request.	"4e67a341-826c-4813-99b4-6c91cf2de4f7"
   workflow	String	Name of the workflow executed.	"consumer_onboarding"
   workflow_id	String (UUID)	Unique identifier for the workflow run.	"63e7534e-675e-4e7b-985b-f578d98347d0"
   workflow_version	String	Version of the executed workflow.	"11.71.0"
   eval_source	String (enum)	Indicates where the evaluation was initiated from. Possible values: API, Dashboard.	"API"
   eval_id	String (UUID)	RiskOS-generated unique identifier for the evaluation. Persist this value to correlate webhooks and GET requests.	"1cc8f438-3c65-47ec-a1de-ad828dbcfa25"
   eval_start_time	String <Date-Time>	RFC 3339 timestamp when RiskOS™ began processing the evaluation.	"2026-02-17T23:16:06.555204712Z"
   eval_end_time	String <Date-Time>	RFC 3339 timestamp when processing completed or paused.	"2026-02-17T23:16:06.555902399Z"
   decision	String (enum)	Evaluation result. Possible values include ACCEPT, REVIEW, REJECT, RESUBMIT.	"REVIEW"
   decision_at	String <Date-Time>	RFC 3339 timestamp when the decision was finalized.	"2026-02-17T23:16:06.555912097Z"
   status	String (enum)	Case-level status of the evaluation. Possible values: OPEN, CLOSED, ON_HOLD.	"ON_HOLD"
   sub_status	String	Provides additional detail about the evaluation status.	"More information needed"
   eval_status	String (enum)	Internal evaluation lifecycle state. Possible values: evaluation_completed, evaluation_paused, evaluation_in_progress.	"evaluation_paused"
   tags	Array of Strings	Labels applied during the workflow to highlight routing decisions or notable signals.	[]
   review_queues	Array of Strings	Manual review queues the evaluation was sent to.	["Default Queue"]
   notes	String	Freeform text for analyst or system comments about the evaluation.	""
   environment_name	String	Environment where the evaluation was executed. Typically Sandbox or Production.	"Sandbox"

3. Redirect and launch the Hosted Flow

   Immediately redirect the user to the redirect_uri returned in the evaluation response. RiskOS™ now manages the full onboarding experience.

   
   

   During the hosted session, RiskOS™ may:

   • Collect phone number and date of birth
   • Perform KYC and Watchlist screening
   • Step-up to Document Verification (DocV), if risk thresholds are met

   
   

   Web integration

   If integrating in a web application, redirect the user to the hosted redirect_uri. You may open it in the same tab or a new tab.

   JavaScript

   window.location.href = hostedRedirectUri

   
   

   Native iOS integration

   Launch the RiskOS™ Hosted Flow using an in-app browser such as SFSafariViewController.

   Swift

   import SafariServices
   
   let safariVC = SFSafariViewController(url: URL(string: hostedRedirectUri)!)
   present(safariVC, animated: true)

   
   

   Native Android integration

   Launch the RiskOS™ Hosted Flow using Chrome Custom Tabs for a secure in-app browser experience.

   Kotlin

   val customTabsIntent = CustomTabsIntent.Builder().build()
   customTabsIntent.launchUrl(this, Uri.parse(hostedRedirectUri))

   
   

   Your application does not collect or process PII during this stage.

   
   

   Important: The redirect indicates the UX is complete. The final decision is delivered asynchronously via webhook.

4. 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"
               }
           }
           }
       }
       ]
   }
   }

   
   

   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"

5. 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");
   }