Integrating with RiskOS™

RiskOS™ is Socure's real-time identity and risk decisioning platform. It connects your applications to Socure's products using REST APIs and webhooks, enabling you to evaluate users, detect fraud, and automate compliance decisions in real time.

What you can do with RiskOS™

How it works

flowchart LR
    EndUser[Consumer]
    Customer["Your Application"]
    RiskOS["RiskOS™ Platform"]

    EndUser -->|Initiates Action| Customer
    Customer -->|Sends Data / Request| RiskOS
    RiskOS -->|Returns Decision / Response| Customer
    Customer -->|Delivers Result| EndUser

• Your application sends a POST request to the Evaluation API with user data and a workflow name.
• RiskOS™ runs the workflow and returns a JSON response with a decision, risk scores, reason codes, and enrichment data.
• Workflows with asynchronous steps (DocV, OTP) pause instead of deciding immediately — you get the final result via webhook or by polling with a GET request.

Endpoints

All requests use the Evaluation API base URL for your environment (see Step 1).

Before you start

Confirm you have the following:

Step 1: Set up your environment

Choose your environment

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

Get your API key

1. Log in to the RiskOS™ Dashboard for your environment:
   • Sandbox Dashboard
   • Production Dashboard
2. Go to Developer Workbench > API Keys.
3. Copy your API key and store it securely.

(Optional) Configure IP allowlisting

1. Go to Developer Workbench > IP Filtering (Sandbox | Production).
2. Add your IP addresses or domains, separated by commas, in the Domain Name field.
3. Test access after configuration.

Step 2: Build a workflow

Workflows are decision strategies you build visually in the Workflow Builder. Once published, your application triggers a workflow by calling the Evaluation endpoint.

A typical workflow includes these step types:

Step 3: Send your first evaluation

Authentication and headers

Include your API key as a Bearer token and 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

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "id": "ind-9876543",
        "given_name": "Jane",
        "family_name": "Smith",
        "national_id": "123456789",
        "date_of_birth": "1990-05-15",
        "email": "[email protected]",
        "phone_number": "+1-312-555-1234",
        "address": {
          "line_1": "742 Evergreen Terrace",
          "line_2": "Apt 12B",
          "locality": "Springfield",
          "major_admin_division": "IL",
          "country": "US",
          "postal_code": "62704"
        },
        "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
      }
    }
  }'

{
  "id": "onb-12345",
  "timestamp": "2023-12-01T08:15:30.456Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "id": "ind-9876543",
      "given_name": "Jane",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1990-05-15",
      "email": "[email protected]",
      "phone_number": "+1-312-555-1234",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
    }
  }
}

Request fields

Step 4: Handle the response

The response you receive depends on whether your workflow is synchronous (all steps complete inline) or asynchronous (contains steps that pause for user action).

Every response carries four fields that describe different things. Read them together rather than in isolation:

{
  "id": "onb-12345",
  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
  "workflow": "consumer_onboarding",
  "eval_status": "evaluation_completed",
  "decision": "REJECT",
  "status": "CLOSED",
  "sub_status": "Reject",
  "workflow_id": "472288ff-b3a8-4e69-89dd-069d5e2bcb41",
  "workflow_version": "3.7.0",
  "eval_source": "API",
  "eval_start_time": "2024-12-02T10:28:24.456Z",
  "eval_end_time": "2024-12-02T10:29:10.999Z",
  "score": 146,
  "tags": ["High Risk", "Bad Device"],
  "review_queues": ["business_review"],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Address risk",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": { ... },
      "response": {
        "addressRisk": {
          "reasonCodes": ["I704", "I705", "I708"],
          "score": 0.01
        },
        "referenceId": "4ca693ee-af2a-45ef-9688-834683ac1b34"
      }
    }
  ],
  "environment_name": "Sandbox"
}

{
  "id": "a86580cc-1733-4188-86b5-717166e1db8c",
  "eval_id": "588dad8b-86ea-43af-94ba-15d07a0e7db5",
  "workflow": "trust_and_safety",
  "eval_status": "evaluation_paused",
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "sub_status": "Surveillance",
  "workflow_id": "08b17f2a-bf94-429e-aaae-3c16fee38bec",
  "workflow_version": "3.0.0",
  "eval_source": "API",
  "eval_start_time": "2025-11-04T19:26:37.800Z",
  "eval_end_time": "2025-11-04T19:26:37.804Z",
  "data_enrichments": [
    {
      "enrichment_name": "Socure Document Request - Default Flow",
      "response": {
        "data": {
          "docvTransactionToken": "6a95fcbd-4f42-4673-890f-ca90cd54f7f0",
          "url": "https://verify.socure.com/#/dv/6a95fcbd-4f42-4673-890f-ca90cd54f7f0"
        }
      }
    }
  ],
  "environment_name": "Sandbox"
}

curl --request PATCH \
  --url https://riskos.sandbox.socure.com/api/evaluation/{eval_id} \
  --header "accept: application/json" \
  --header "content-type: application/json" \
  --header "authorization: Bearer YOUR_API_KEY" \
  --data '{
    "id": "a86580cc-1733-4188-86b5-717166e1db8c",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "trust_and_safety",
    "data": {
      "individual": {
        "phone_number": "+1-202-555-9999"
      }
    }
  }'

{
"data": {
  "individual": {
    "phone_number": "+1-202-555-9999"
  }
},
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"timestamp": "2023-12-01T08:15:30.456Z",
"workflow": "trust_and_safety"
}

curl --request PUT \
  --url https://riskos.sandbox.socure.com/api/evaluation/{eval_id}/state \
  --header "content-type: application/json" \
  --header "authorization: Bearer YOUR_API_KEY" \
  --data '{
    "workflow": "trust_and_safety",
    "decision": "REVIEW",
    "status": "OPEN",
    "sub_status": "In Review",
    "notes": "Verification documents pending re-check",
    "attachments": [
      {
        "file_name": "case.jpeg",
        "file_data": "JVBERi0xLjUKJeLjz9MKMyAwIG9iago8PC9..."
      }
    ]
  }'

{
  "workflow": "trust_and_safety",
  "decision": "REVIEW",
  "status": "OPEN",
  "sub_status": "In Review",
  "notes": "Verification documents pending re-check",
  "attachments": [
    {
      "file_name": "case.jpeg",
      "file_data": "JVBERi0xLjUKJeLjz9MKMyAwIG9iago8PC9..."
    }
  ]
}

{
  "id": "a86580cc-1733-4188-86b5-717166e1db8c",
  "eval_id": "1e85e088-ade0-4ef6-bb6d-3524da429114",
  "workflow": "trust_and_safety",
  "eval_status": "evaluation_completed",
  "decision": "ACCEPT",
  "status": "CLOSED",
  "sub_status": "Accept",
  "workflow_id": "cdefa08b-5dce-4b0a-a87a-23693c01b5e5",
  "workflow_version": "4.36.0",
  "data_enrichments": [
    {
      "enrichment_name": "Socure Document Verification - Default Flow",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "response": {
        "documentVerification": {
          "decision": { "name": "standard", "value": "accept" },
          "documentData": {
            "firstName": "Jane",
            "surName": "Smith",
            "dob": "1980-01-01",
            "documentNumber": "11223344",
            "documentType": { "country": "USA", "state": "NY", "type": "Drivers License" }
          },
          "reasonCodes": ["I831", "I836"]
        }
      }
    }
  ],
  "environment_name": "Sandbox"
}

Step 5: Handle manual review cases

When a workflow cannot reach an automatic decision, it returns "decision": "REVIEW" and routes the case to Case Management for human review.

Common triggers for manual review:

Response field reference

These tables describe the fields returned in every evaluation response. They apply to both synchronous and asynchronous flows.

Top-level fields

data_enrichments fields

Each object in the data_enrichments array represents one enrichment call:

Enrichment response objects

The response object within each enrichment varies by product. See the integration guide for each enrichment:

Reason codes and scores

Each enrichment nests a reasonCodes array alongside its score inside data_enrichments[].response.<enrichmentName>. The score tells you how risky an attribute is; the reason codes explain why. For example, the addressRisk object earlier in this topic returns "reasonCodes": ["I704", "I705", "I708"].

To interpret these values in your decision handling:

• Reason Codes & Score Interpretation — how to read a score, what the I and R prefixes mean, and where each code appears in the response.
• Interpret a Decline — trace a REVIEW or REJECT decision back to the scores and reason codes that drove it.
• List Reason Codes — retrieve the full code catalog and descriptions programmatically.

Webhooks

RiskOS™ sends HTTPS POST requests to your configured endpoints when subscribed events occur, such as completed evaluations, case updates, or watchlist changes. Webhooks support Basic, Bearer, and OAuth 2.0 authentication with built-in retry logic.

Configure webhook endpoints and event subscriptions in the RiskOS™ Dashboard. See the Webhooks guide and Event subscription types for details.

Troubleshooting

Validation checklist

Next steps