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

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 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 and submit identity data  
Use the Consumer Onboarding workflow to verify PII while minimizing user friction.

### Collect required input  
Your application must collect the required fields before initiating the workflow. Validate the following client-side before submission:

**Minimum required**
- `given_name`
- `family_name`
- `address.country`
- `di_session_token` (must be generated from the active Digital Intelligence session)
- Plus at least one of:
  - `date_of_birth`
  - `phone_number`
  - Address fields (for example, `address.line_1`, `address.locality`, etc.)

**Recommended (highest match accuracy)**
> Include all minimum required fields in addition to the fields below.
- `date_of_birth` (must be in `YYYY-MM-DD` format)
- `phone_number` (must be in E.164 format)
- `email`
- `address.line_1`
- `address.locality` (city)
- `address.major_admin_division` (region/state)
- `address.postal_code`
- `national_id` (e.g., SSN)

## Step 3: Create an evaluation  
Make a `POST` request to the [Evaluation endpoint](https://help.socure.com/riskos/reference/postevaluation) using the Consumer Onboarding 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.socure.com/api/evaluation \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{\n    "id": "fb428165-6a1c-4d36-afbc-c8a946c1287d",\n    "timestamp": "2026-02-17T14:22:06.628Z",\n    "workflow": "consumer_onboarding",\n    "data": {\n      "individual": {\n        "given_name": "Stanley",\n        "family_name": "Brown",\n        "date_of_birth": "1944-03-30",\n        "address": {\n          "country": "US"\n        },\n        "di_session_token": "fadsadfassdjhbwf-2232-dsdwd2-212e235"\n      }\n    }\n  }'
```

```json
{
  "id": "fb428165-6a1c-4d36-afbc-c8a946c1287d",
  "timestamp": "2026-02-17T14:22:06.628Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Stanley",
      "family_name": "Brown",
      "date_of_birth": "1944-03-30",
      "address": {
        "country": "US"
      },
      "di_session_token": "fadsadfassdjhbwf-2232-dsdwd2-212e235"
    }
  }
}
```

### Field definitions  
| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | String | Required | Unique identifier for the evaluation. Must be unique per request; reused IDs trigger re-runs and may affect downstream behavior. | `"fb428165-6a1c-4d36-afbc-c8a946c1287d"` |
| `timestamp` | String `<Date-Time>` | Required | RFC 3339 timestamp when the evaluation was initiated. | `"2026-02-17T14:22:06.628Z"` |
| `workflow` | String | Required | Environment-specific workflow identifier configured in RiskOS™. Must map to a single active workflow. | `"consumer_onboarding"` |
| `data.individual.given_name` | String | Required | Consumer’s first name (max 240 characters). | `"Stanley"` |
| `data.individual.family_name` | String | Required | Consumer’s last name (max 240 characters). | `"Brown"` |
| `data.individual.date_of_birth` | String | Optional | Date of birth in `YYYY-MM-DD` format. | `"1944-03-30"` |
| `data.individual.di_session_token` | String (UUID) | Required | Digital Intelligence session token linking device data. | `"8ceed175-37ae-4eb4-9ee5-b7fc5d7c1799"` |
| `data.individual.address.country` | String | Required | Country (ISO 3166-1 alpha-2). | `"US"` |

## 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:
- Accept the user
- Stop the flow
- Collect additional identity data
- Continue with additional verification

## Next steps  
Process the evaluation response and route the consumer based on the decision, tags, and step-up signals.