Submit Prefilled Data via API

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

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

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

The following fields are nested under data.individual.docv.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:

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