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

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

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 Flow experience

Configure your hosted onboarding UI in 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": "advanced_pre_fill",
    "data": {
      "custom": {
        "redirect_uri": "https://yourapp.com/callback"
      }
    }
  }'

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

Required fields

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

Field	Description
`id`	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.
`timestamp`	RFC 3339 timestamp indicating when the evaluation request was initiated by your system.
`workflow`	RiskOS™ workflow name configured in your environment.
`data.custom.redirect_uri`	URL where the user returns after completing the Hosted Flow. Required to launch and return from the hosted experience.

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

Optional: Document Verification

Use these optional fields to customize DocV behavior:

Field	Description
`config.send_message`	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
`config.language`	Determines Capture App UI language. Defaults to `en-us`.
`config.use_case_key`	Deploys a specific Capture App flow created in RiskOS™.
`config.document_type`	Restrict to a single document type (`license` or `passport`) for a simplified flow. Users skip the document type selection screen when passed.
`config.redirect.url`	Required if `redirect` is provided. The destination URL to send the consumer after capture. Can include query strings for transaction tracking.
`config.redirect.method`	Required if `redirect` is provided. Accepts `GET` or `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"
}

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.

Tip: A "decision": "REVIEW" response includes the hosted redirect_uri, which is required to launch the experience.

Step 3: Redirect the user

Immediately redirect the user to the redirect_uri returned in the evaluation response to launch the hosted flow.

RiskOS™ then handles:

Identity data collection
Fraud checks
Watchlist screening
Optional One-Time Passcode and Document Verification step-up

RiskOS™ may step up verification during the hosted session, including:

Government ID capture
Biometric selfie
Liveness verification

Summary

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