## 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](https://help.socure.com/riskos/docs/webhooks) to receive asynchronous `evaluation_completed` events.

## 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
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](https://help.socure.com/riskos/reference/postevaluation).

#### 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](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. | `https://example.com`<br>`/complete` |
| `redirect.method` | String (Enum: `GET` \| `POST`) | Conditional | HTTP method used for the redirect. Required if `redirect` is provided. | `POST` |

### Example response

JSON

```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](https://help.socure.com/riskos/reference/postevaluation).

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

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

## Summary

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