Integration Guide

Sigma Identity Fraud API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the Sigma Identity Fraud enrichment. You’ll learn how to send identity data, parse the response, and apply decision logic to support onboarding, trust and safety, fraud prevention, or compliance workflows.

Before you start

Make sure your RiskOS™ environment is provisioned with:

Choose your environment

Start with Sandbox for development and testing, then move to Production for live applications.

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

Get an API key

How it works

1. Send a POST request to /api/evaluation with identity data.
2. Socure runs the request through configured RiskOS™ workflow with tailored enrichments.
3. Receive a decision (ACCEPT, REVIEW, or REJECT) and supporting metadata.
4. Apply your routing logic based on the result.

Start a new Risk Evaluation

Endpoint

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

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

Authentication and headers

Include your API key in the Authorization header as a Bearer token, along with standard JSON headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion   # optional – pins a specific API version

Example request

📘

Note:

Do not pass placeholder or dummy values for any of these fields when you are not able to collect them from the end-user. Passing such values will lead to reduced accuracy and can impact future predictions. If you are not able to collect a field value from the consumer, pass null for that field.

{
  "id": "APP-123456",
  "timestamp": "2022-07-28T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Shannon",
      "family_name": "Zhao",
      "national_id": "123456789",
      "date_of_birth": "1958-01-31",
      "email": "[email protected]",
      "phone_number": "+13475551234",
      "address": {
        "line_1": "234 Main Street",
        "line_2": "Apt. 3C",
        "locality": "Jersey City",
        "major_admin_division": "NJ",
        "country": "US",
        "postal_code": "07307"
      }
    },
    "ip_address": "10.10.10.10"
  }
}

curl --location --request POST 'https://riskos.sandbox.socure.com/api/evaluation' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
    "id": "APP-123456",
    "timestamp": "2022-07-28T06:10:54.298Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "given_name": "Shannon",
        "family_name": "Zhao",
        "national_id": "123456789",
        "date_of_birth": "1958-01-31",
        "email": "[email protected]",
        "phone_number": "+13475551234",
        "address": {
          "line_1": "234 Main Street",
          "line_2": "Apt. 3C",
          "locality": "Jersey City",
          "major_admin_division": "NJ",
          "country": "US",
          "postal_code": "07307"
        }
      },
      "ip_address": "10.10.10.10"
    }
  }'

Request schema

Top-level fields

📘

Note:

The Sigma Identity Fraud product makes use of multiple input fields to determine both the score and reason codes. For the highest accuracy and performance all these fields should be collected and passed in the input, however the product will still work when select fields are not provided.

individual fields

address fields

Example response

When you call the Evaluation API, RiskOS™ returns a JSON payload that includes the final decision, evaluation metadata, and enrichment-specific results.

{
  "id": "APP-123456",
  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
  "decision": "REVIEW",
  "tags": [],
  "review_queues": [],
  // ...
  "data_enrichments": [
    {
      "enrichment_name": "Socure Sigma Identity Fraud",
      "enrichment_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        // ...
      },
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "fraud": {
          "reasonCodes": [
            "R617",
            "R613",
            "I625",
            "R705",
            "I614",
            "R703",
            "R551",
            "R563",
            "R611"
          ],
          "scores": [
            {
              "name": "sigma",
              "version": "4.0",
              "score": 0.957
            }
          ]
        }
      }
    }
  ]
}

Key response fields

RiskOS™ returns a consistent set of top-level fields that describe the outcome of an evaluation, along with enrichment-specific results that depend on your workflow configuration.

Where to find specific results

Decision and routing (primary control signals)

Use these fields to determine what action your application should take.

decision values are workflow-specific and may differ from the examples shown in this guide.

Evaluation lifecycle and status

These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.

Identifiers and traceability

Use these fields to correlate requests, logs, webhooks, and support cases.

Execution context

These fields provide timing and environment context for the evaluation.

Enrichment results

Enrichment outputs are returned in the data_enrichments array.

request fields

response fields

fraud fields

scores fields