Start a New Evaluation

Use the Direct API to collect identity data, verify users, and screen for sanctions.

Many evaluations complete immediately. When additional verification is required, RiskOS™ continues the evaluation through step-up verification such as Document Verification (DocV).

Before you start

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 to your project using npm:

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.

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

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

This request starts the evaluation using the identity data collected in your application.

Persist the eval_id from the response to track and continue the evaluation.

RiskOS™ evaluates device and phone risk signals and may return a final decision immediately or require additional verification.

The response determines how your application should proceed, such as prompting for a One-Time Passcode, collecting additional identity data, or continuing with prefilled information.

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": "non_hosted_advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155550001",
        "date_of_birth": "1990-05-15",
        "di_session_token": "sess_123",
        "address": {
          "country": "US"
        }
      }
    }
  }'

{
  "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

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:

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
• Collect additional identity data
• Display prefilled data
• Continue with additional verification

For response handling patterns and routing logic, see Handle Results.