Submit Data for KYC + Fraud + Watchlist via API

Before you start

Get your API key and SDK key from the API & SDK Keys page in the RiskOS™ Dashboard.

Use the Sandbox base URL riskos.sandbox.socure.com for all requests.

Register a webhook endpoint 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 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

Recommended (highest match accuracy)

Include all minimum required fields in addition to the fields below.

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 '{\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  }'

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

Next steps

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