Start DocV with Socure Pass in Hosted Flow
Before you start
Use the Sandbox base URL [https://riskos.sandbox.socure.com](https://riskos.sandbox.socure.com) for all requests.
Register your webhook endpoint to receive asynchronous evaluation_completed events.
Step 1: Customize the hosted experience
Add your logo, branding, and customized copy on the Templates tab in the RiskOS™ Dashboard.
This includes:
- Branding (logo, colors)
- User-facing copy
- Flow configuration
Step 2: Create an evaluation
This request initializes the Hosted Flow and places the evaluation in a paused state while RiskOS™ collects identity data from the user.
The response includes a redirect_uri that you use to launch the hosted flow. Use this value in Step 3 to redirect the user.
Endpoint
Start with Sandbox for development and testing, then move to Production for live applications.
POST https://riskos.sandbox.socure.com/api/evaluation
POST https://riskos.socure.com/api/evaluation
Minimum working request
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 '{\n "id": "17e9a02a-a5a7-442b-9b28-2034e1ed9d53",\n "timestamp": "2025-08-14T20:10:04.535Z",\n "workflow": "docv_socure_pass",\n "data": {\n "custom": {\n "redirect_uri": "https://yourapp.com/callback"\n }\n }\n}'
Required fields
The following fields must be provided to create a Hosted Flow evaluation:
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
id |
String | Required | Unique identifier for the evaluation request | "fb428165-6a1c-4d36-afbc-c8a946c1287d" |
timestamp |
String (ISO 8601) | Required | Time the request is created | "2026-02-17T14:22:06.628Z" |
workflow |
String | Required | Workflow name configured in RiskOS™ | "docv_socure_pass" |
data.custom.redirect_uri |
String (URL) | Optional | URL to redirect user after flow completion. If not provided, the user remains on the Socure-hosted completion screen. | https://example.com/complete |
For complete request field definitions and advanced configuration options, see the Evaluation API Reference.
Optional: Document Verification
The following fields nest under data.individual.docv.config. Use these optional fields to customize document verification behavior.
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
send_message |
Boolean | Optional | Set to true to send an SMS to the provided phone number with the document request URL. Defaults to false. |
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™. | default_docv_flow |
document_type |
String (Enum: license | passport) |
Optional | Restrict the flow to a single document type. When provided, users skip the document type selection screen. | passport |
redirect.url |
String (URL) | Conditional | Destination URL to send the consumer after capture. Required if redirect is provided. |
https://example.com/complete |
redirect.method |
String (Enum: GET | POST) |
Conditional | HTTP method used for the redirect. Required if redirect is provided. |
POST |
Example response
JSON
{
"eval_id": "6c3e1165-1617-4417-b759-92176c75c6e5",
"status": "ON_HOLD",
"decision": "REVIEW",
"eval_status": "evaluation_paused",
"redirect_uri": "https://riskos.sandbox.socure.com/hosted/xyz"
}
For the full response schema and all available fields, see the Evaluation API Reference.
Response notes
| Field / Value | Description |
|---|---|
eval_id |
Unique identifier used to correlate webhook events with this evaluation. |
status: ON_HOLD |
Indicates the evaluation is waiting for user interaction. |
eval_status: evaluation_paused |
Indicates the evaluation is paused during the hosted flow. |
decision: REVIEW |
Expected initial decision; does not represent the final outcome. |
redirect_uri |
URL used to launch the hosted onboarding experience. |
Step 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™:
- Authenticate returning users via Socure Pass passkey
- Collect explicit consent before sharing data
- Guide new users through Document Verification (ID scan, selfie, liveness)
- Offer Socure Pass enrollment after successful verification
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
Hosted Flows for iOS enables you to launch the RiskOS™ Hosted Flow from your iOS app by 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
Hosted Flows for Android enables you to 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))
Summary
- Customize the hosted experience.
- Create the evaluation via API.
- Redirect the user to the Hosted Flow.