## Before you start

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

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 Direct API integration in Sandbox.

## Step 1: Set up the Digital Intelligence session token

Before submitting an evaluation, generate a device-specific `di_session_token`. This short-lived token helps verify device integrity and is required for certain RiskOS™ evaluations.

### Install the Digital Intelligence SDK

Add the [Digital Intelligence Web SDK](https://help.socure.com/riskos/docs/digital-intelligence-web-sdk) to your project using npm:

```shell
npm install --save @socure-inc/device-risk-sdk
```

### Initialize the SDK once per session

Mount the `SocureInit` component in a high-level file (such as `layout.tsx`) to initialize the SDK once per session. This prevents redundant re-initialization during navigation.

```jsx
"use client";

import { useEffect, useRef } from "react";
import { SigmaDeviceManager, SigmaDeviceOptions } from "@socure-inc/device-risk-sdk";

export function SocureInit() {
  const initializedRef = useRef(false);

useEffect(() => {
    if (initializedRef.current) return;
    const sdkKey = process.env.NEXT_PUBLIC_SOCURE_SDK_KEY;

if (sdkKey) {
      SigmaDeviceManager.initialize({ sdkKey } as SigmaDeviceOptions);
      initializedRef.current = true;
    }
  }, []);

return null;
}
```

### Generate a session token

Immediately before submitting a form to your backend, call `getSessionToken()`. Include the resulting string in your API request payload as the `di_session_token` field.

```tsx
// Call this inside your form submission handler
export async function getSessionToken() {
  return SigmaDeviceManager.getSessionToken();
}
```

## Step 2: Collect initial identity data

Before you create an evaluation, your application must collect the required fields. Validate the following client-side before submission:

- `date_of_birth` must be in YYYY-MM-DD format.
- `phone_number` must be in E.164 format.
- `address.country` must be in ISO 3166-1 alpha-2 country code.
- `di_session_token` must be generated from the active Digital Intelligence session.

> 👍
>
> **Tip**:
>
> Adding additional personally identifiable information (PII) can improve match accuracy.

## Step 3: Create an evaluation

Make a `POST` request to the [Evaluation endpoint](https://help.socure.com/riskos/reference/postevaluation) using the Advanced Prefill workflow. This request starts the evaluation using the identity data collected in your application.

### 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 '{
    "id": "session_12345",
    "timestamp": "2026-01-01T12:00:00Z",
    "workflow": "non_hosted_advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155550001",
        "date_of_birth": "1990-05-15",
        "di_session_token": "sess_123",
        "address": {
          "country": "US"
        }
      }
    }
  }'
```

```json
{
  "id": "session_12345",
  "timestamp": "2026-01-01T12:00:00Z",
  "workflow": "non_hosted_advanced_pre_fill",
  "data": {
    "individual": {
      "phone_number": "+14155550001",
      "date_of_birth": "1990-05-15",
      "di_session_token": "sess_123",
      "address": {
        "country": "US"
      }
    }
  }
}
```

### Required fields

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `id` | String | Required, customer-defined unique identifier for the request.<br>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. | `session_12345` |
| `timestamp` | String (RFC 3339) | **RFC 3339** timestamp indicating when the evaluation request was initiated by your system. | `2026-01-01T12:00:00Z` |
| `workflow` | String | RiskOS™ workflow name configured in your environment. | `non_hosted_advanced_pre_fill` |
| `data.individual.phone_number` | String (E.164) | Phone number in **E.164 format**. The API expects the standard E.164 format but tolerates hyphens and spaces for user convenience. | `+14155550001` |
| `data.individual.date_of_birth` | String (YYYY-MM-DD) | Consumer date of birth in `YYYY-MM-DD` format. | `1990-05-15` |
| `data.individual.di_session_token` | String (UUID) | Digital Intelligence SDK session token (UUID format). | `sess_123` |
| `data.individual.address.country` | String (ISO 3166-1 alpha-2) | Consumer country in **ISO 3166-1 alpha-2 format**. | `US` |

#### 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`.<br>\- **US & Canada**: sent from short code 33436<br>\- **Other countries**: sent from +1 (510) 330-19xx | `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`<br>`/complete` |
| `redirect.method` | String (Enum: `GET` \| `POST`) | Conditional | HTTP method used for the redirect. Required if `redirect` is provided. | `POST` |

## Step 4: Continue based on the response

After you create an evaluation, RiskOS™ returns a response that determines the next step in your flow.

Use `decision`, `sub_status`, and `tags` to determine whether to:

- Stop the flow
- Prompt for One-Time Passcode (OTP)
- Collect additional identity data
- Display prefilled data
- Continue with additional verification

For response handling patterns and routing logic, see [Handle Results](https://help.socure.com/riskos/docs/prefill-kyc-fraud-watchlist-direct-api-handle-results).