## Before you start

Get your **API key** from the [API & SDK Keys](https://riskos.sandbox.socure.com/developers/key-management) page in the RiskOS™ Dashboard.

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

Register a [webhook endpoint](https://help.socure.com/riskos/docs/webhooks) to receive `evaluation_completed` events for asynchronous decisions.

## 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](https://riskos.sandbox.socure.com/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.

```http
POST https://riskos.sandbox.socure.com/api/evaluation
```

```http
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": "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  }'
```

```json
{
  "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](https://help.socure.com/riskos/docs/language-options). Defaults to `en-us`. | `en-us` |
| `use_case_key` | String | Optional | Deploys a specific [Capture App flow](https://help.socure.com/riskos/docs/capture-app-setup) 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`<br>`/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"
}
```

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

```javascript
window.location.href = hostedRedirectUri
```

### Native iOS integration

[Hosted Flows for iOS](https://help.socure.com/riskos/docs/hosted-flows-ios) enables you to launch the RiskOS™ Hosted Flow from your iOS app by using an in-app browser such as `SFSafariViewController`.

Swift

```swift
import SafariServices

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

### Native Android integration

[Hosted Flows for Android](https://help.socure.com/riskos/docs/hosted-flows-android) enables you to launch the RiskOS™ Hosted Flow using Chrome Custom Tabs for a secure in-app browser experience.

Kotlin

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

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

## Summary

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