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 in real time and returns a JSON response containing a decision, risk scores, reason codes, and enrichment data.

Some workflows include asynchronous steps such as Document Verification (DocV) or One-Time Passcode (OTP) validation. In these cases, the evaluation pauses and resumes when the user completes the required action. You receive the final result through a webhook or by polling with a GET request.

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

📘

Note:

IP allowlisting restricts which IPs can call the API. It is separate from your API key, which authenticates the caller. See the IP Filtering guide for details.

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 automated decision strategies built visually in the RiskOS™ Dashboard using the Workflow Builder. Once published, a workflow runs when your application calls the Evaluation endpoint.

A typical workflow includes these step types:

👍

Tip:

RiskOS™ provides pre-built workflow templates for common use cases. See the Integration Guides to get started.

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

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

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:

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:

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