Start KYC + Fraud + Watchlist in Hosted Flow

Before you start

Get your API key from the API & SDK Keys page in the RiskOS™ Dashboard.

Use the Sandbox base URL riskos.sandbox.socure.com for all requests.

Test with Postman

Use this Postman collection to send sample requests to the Evaluation API and validate your Hosted Flow integration in Sandbox.

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 --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": "session_12345",\n    "timestamp": "2026-01-01T12:00:00Z",\n    "workflow": "consumer_onboarding",\n    "data": {\n      "custom": {\n        "redirect_uri": "https://yourapp.com/callback"\n      }\n    }\n  }'

{
  "id": "session_12345",
  "timestamp": "2026-01-01T12:00:00Z",
  "workflow": "consumer_onboarding",
  "data": {
    "custom": {
      "redirect_uri": "https://yourapp.com/callback"
    }
  }
}

Required fields

The following fields are required to create a Hosted Flow evaluation:

Field	Type	Required	Description	Example
`id`	String	Required	Unique identifier for the evaluation request	`eval-123456`
`timestamp`	String (ISO 8601)	Required	Time the request is created	`2026-04-21T18:25:43Z`
`workflow`	String	Required	Workflow name configured in RiskOS™	`consumer_onboarding`
`data.custom.redirect_uri`	String (URL)	Required	URL to redirect user after flow completion	`https://example.com/complete`

Optional: Document Verification

The following fields are nested 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. Can include query strings for transaction tracking.	`https://example.com/complete` `/complete`
`redirect.method`	String (Enum: `GET` \| `POST`)	Conditional	HTTP method used for the redirect. Required if `redirect` is provided.	`POST`

Example response

{
  "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"
}

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

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

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

Summary

Customize the hosted experience.
Create the evaluation via API.
Redirect the user to the Hosted Flow.