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™

Send evaluations

Submit evaluation requests with user or transaction data to trigger real-time workflows.

Get instant decisions

Receive structured risk insights and decision outcomes: ACCEPT, REJECT, or REVIEW.

Stay in sync

Subscribe to webhook events for completed evaluations, case updates, and watchlist changes.

How it works

Initiates Action

Sends Data / Request

Returns Decision / Response

Delivers Result

Consumer

Your Application

RiskOS™ Platform

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:

• RiskOS™ Dashboard access with appropriate user permissions.
• At least one published workflow in the RiskOS™ Dashboard.

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:

HTTP

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

cURLJSON

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": "jane.smith@example.com",
        "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": "jane.smith@example.com",
      "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).

Synchronous workflows return a final decision immediately. This is the typical flow for identity verification, fraud screening, and risk scoring without user interaction steps.

Response: HTTP 200 with the complete evaluation result.

JSON

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

Asynchronous workflows pause when they reach a step that requires user action, such as Document Verification (DocV) or OTP validation.

Initial response: HTTP 201 with eval_status: "evaluation_paused" and no final decision.

JSON

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

Resume or update a paused evaluation

If additional data is required, resume the evaluation by sending a PATCH or PUT request to /api/evaluation/<eval_id>:

cURLJSON

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

cURLJSON

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..."
    }
  ]
}

Final result delivery

When the asynchronous step completes, RiskOS™ delivers the final decision through a webhook (evaluation_completed event). You can also retrieve results with a GET /api/evaluation/<eval_id> request.

JSON

{
  "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": "Doe",
            "dob": "1980-01-01",
            "documentNumber": "11223344",
            "documentType": { "country": "USA", "state": "NY", "type": "Drivers License" }
          },
          "reasonCodes": ["I831", "I836"]
        }
      }
    }
  ],
  "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

Request setup:

• Correct endpoint set for environment (Sandbox or Production): /api/evaluation
• Authorization header includes a valid Bearer API key with standard JSON headers
• Request body includes required fields: id, timestamp, workflow, and data.individual

Workflow behavior:

• workflow name matches an active, published workflow in the RiskOS™ Dashboard
• Optional fields used by workflow rules are included when applicable (for example, line_of_business, channel, ip_address)

Response handling:

• Parse key fields: decision, status, sub_status, eval_id, data_enrichments
• Synchronous path: handle the immediate JSON response (ACCEPT / REJECT / REVIEW)
• Asynchronous path: handle webhooks or poll with `GET /api/evaluation/

Error and retry handling:

• Implement retries with backoff for transient errors (HTTP 5xx, 429)
• Surface validation errors (4xx) clearly without retrying
• Log request identifiers (id, eval_id) for troubleshooting

Go-live validation:

• Test a successful evaluation with sample data and confirm expected decision and enrichments
• Confirm webhook delivery and processing for async workflows

Next steps

[Integration guides

Step-by-step guides for specific enrichments and solutions.](https://help.socure.com/riskos/docs/integration-guides)

[API reference

Full Evaluation API specification with request and response schemas.](https://help.socure.com/riskos/reference/postevaluation)

[Webhooks

Configure event-driven notifications for your integration.](https://help.socure.com/riskos/docs/webhooks)