Start a New Evaluation

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

Before you start

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

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

Required fields

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

For complete request field definitions and advanced configuration options, see the Evaluation API Reference.

Optional: Document Verification

The following fields are nested under data.individual.config. Use these optional fields to customize document verification behavior.

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

For the full response schema and all available fields, see the Evaluation API Reference.

Response notes

👍

Tip:

A "decision": "REVIEW" response includes the hosted redirect_uri, which is required to launch the 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.

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.

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.

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.

Summary

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