Start a New Evaluation

Use the Direct API to collect identity data, verify users, and screen against global watchlists with full control over your onboarding experience.

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

👍

Tip:

Adding additional personally identifiable information (PII) can improve match accuracy.

Step 3: Create an evaluation

Make a POST request to the Evaluation endpoint 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.

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

POST https://riskos.socure.com/api/evaluation

Minimum working request

curl --request POST \
  --url https://riskos.socure.com/api/evaluation \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "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"
      }
    }
  }'

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

Optional: Document Verification

The following fields are nested under data.individual.config. Use these optional fields to customize document verification 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:

• Accept the user
• Stop the flow
• Collect additional identity data
• Continue with additional verification

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