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](https://help.socure.com/riskos/docs/users-and-roles-overview).
- 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.

| Environment | Base URL | Notes |
| --- | --- | --- |
| Sandbox | `https://riskos.sandbox.socure.com/api/evaluation` | No real customer data. Free testing environment. |
| Production | `https://riskos.socure.com/api/evaluation` | Real customer data. API usage charges apply. |

### Get your API key

1. Log in to the RiskOS™ Dashboard for your environment:
   - [Sandbox Dashboard](https://riskos.sandbox.socure.com/developers/api-keys)
   - [Production Dashboard](https://riskos.socure.com/developers/api-keys)
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](https://help.socure.com/riskos/docs/ip-filtering) for details.

1. Go to **Developer Workbench > IP Filtering** ( [Sandbox](https://riskos.sandbox.socure.com/developers/ip-filtering) \| [Production](https://riskos.socure.com/developers/ip-filtering)).
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](https://help.socure.com/riskos/docs/workflow-overview) are automated decision strategies built visually in the RiskOS™ Dashboard using the [Workflow Builder](https://help.socure.com/riskos/docs/create-and-edit). Once published, a workflow runs when your application calls the Evaluation endpoint.

A typical workflow includes these step types:

| Step type | Purpose |
| --- | --- |
| **Input** | Collects applicant data |
| **Enrichment** | Pulls additional data from Socure products or third-party APIs |
| **Condition** | Applies logic to determine workflow branching |
| **Decision** | Finalizes the outcome (accept, reject, or route for manual review) |

> 👍  
> **Tip**:  
> RiskOS™ provides pre-built workflow templates for common use cases. See the [Integration Guides](https://help.socure.com/riskos/docs/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

```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
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..."
      }
    }
  }'
```

```json
{
  "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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | String | Yes | Your unique identifier for this evaluation request |
| `timestamp` | String | Yes | ISO 8601 timestamp when the request was initiated |
| `workflow` | String | Yes | Name of the published workflow in your RiskOS™ Dashboard |
| `data` | Object | Yes | Payload containing individual and contextual information |
| `data.individual` | Object | Yes | Applicant information: name, identifiers, contact data, and address |
| `data.individual.di_session_token` | String | No | Digital Intelligence session token for device fingerprinting |

## 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

```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

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

```json
{
"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
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..."
      }
    ]
  }'
```

```json
{
  "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

```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

| Field | Type | Description |
| --- | --- | --- |
| `id` | String | Your original request `id`, echoed back |
| `eval_id` | String (UUID) | RiskOS™-generated identifier for this evaluation. Use it for `GET` and `PATCH` follow-up requests. |
| `workflow` | String | Workflow name that processed the evaluation |
| `workflow_id` | String (UUID) | Internal workflow configuration identifier |
| `workflow_version` | String | Version of the workflow used |
| `eval_source` | String | How the evaluation was submitted (for example, "API") |
| `eval_start_time` | String (RFC 3339) | When evaluation processing began |
| `eval_end_time` | String (RFC 3339) | When evaluation processing completed |
| `decision` | String | Final decision: `ACCEPT`, `REJECT`, `REVIEW`, or `RESUBMIT` |
| `decision_at` | String (RFC 3339) | When the decision was rendered |
| `status` | String | Case lifecycle status: `OPEN`, `ON_HOLD`, or `CLOSED` |
| `sub_status` | String | Additional context for the status |
| `tags` | Array of Strings | Risk or categorization labels |
| `notes` | String | Freeform notes about the case |
| `review_queues` | Array of Strings | Manual review queues assigned to the case |
| `score` | Number | Computed numerical risk score |
| `data_enrichments` | Array of Objects | All enrichment calls executed and their results (see below) |
| `eval_status` | String | Processing status: `evaluation_completed` or `evaluation_paused` |
| `environment_name` | String | `Sandbox` or `Production` |

### `data_enrichments` fields

Each object in the `data_enrichments` array represents one enrichment call:

| Field | Type | Description |
| --- | --- | --- |
| `enrichment_name` | String | Name of the enrichment service executed |
| `enrichment_provider` | String | Vendor providing the enrichment |
| `status_code` | Integer | HTTP status code from the enrichment call |
| `request` | Object | Payload sent to the enrichment provider |
| `response` | Object | Data returned by the enrichment provider |
| `error_message` | String | Error description (present only on failure) |
| `is_source_cache` | Boolean | Whether the result was served from cache |
| `total_attempts` | Integer | Number of retry attempts before success or failure |

### Enrichment response objects

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

| Response field | Enrichment | Guide |
| --- | --- | --- |
| `addressRisk` | Address Risk | [Address Risk integration guide](https://help.socure.com/riskos/docs/address-risk-integration-guide) |
| `emailRisk` | Email Risk | [Email Risk integration guide](https://help.socure.com/riskos/docs/email-risk-integration-guide) |
| `phoneRisk` | Phone Risk | [Phone Risk integration guide](https://help.socure.com/riskos/docs/phone-risk-integration-guide) |
| `fraud` | Sigma Identity Fraud | [Sigma Identity Fraud integration guide](https://help.socure.com/riskos/docs/sigma-identity-fraud-integration-guide) |
| `synthetic` | Sigma Synthetic Fraud | [Sigma Synthetic Fraud integration guide](https://help.socure.com/riskos/docs/sigma-synthetic-fraud-integration-guide) |
| `digitalIntelligence` | Digital Intelligence | [Digital Intelligence data dictionary](https://help.socure.com/riskos/docs/data-dictionary) |
| `documentVerification` | Predictive DocV | [DocV evaluation API call](https://help.socure.com/riskos/docs/docv-integration-guide) |
| `graphIntelligence` | Graph Intelligence | [Graph Intelligence](https://help.socure.com/riskos/docs/graph-intelligence) |

## 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](https://help.socure.com/riskos/docs/case-management-overview) for human review.

Common triggers for manual review:

| Trigger | Example |
| --- | --- |
| Risk score threshold | Fraud, synthetic, or phone/email risk scores exceed a configured limit |
| Multiple risk signals | Uncorrelated PII, incorrect SSN, or conflicting data |
| Watchlist match | Applicant matches OFAC, PEP, or sanctions list |
| Document verification issue | Ambiguous or failed DocV results |
| Custom rule | A user-defined condition was not met for automatic decision |

## 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](https://help.socure.com/riskos/docs/webhooks) and [Event subscription types](https://help.socure.com/riskos/docs/webhook-events) for details.

## Troubleshooting

| Issue | Cause | Fix |
| --- | --- | --- |
| `401 Unauthorized` | API key is missing, invalid, or does not match the environment (Sandbox vs. Production) | Verify you are using the correct API key for the target environment. Confirm your account has the required permissions. |
| Workflow not executing | The workflow is not published, contains errors, or the wrong workflow name is referenced | Confirm the workflow is saved without errors and set to **LIVE** status. Verify the `workflow` value in your request matches the Dashboard. |
| `400 Bad Request` | Required fields are missing or incorrectly formatted | Confirm all required fields (`id`, `timestamp`, `workflow`, `data.individual`) are present and correctly formatted. |
| Request blocked | Your IP address is not on the allowlist or a firewall blocks outbound traffic | Verify your IP is allowlisted (if configured). Check for network restrictions blocking the Socure API endpoints. |
| Webhook not received | Endpoint is misconfigured, unreachable, or cannot process the payload | Confirm [webhook endpoints are correctly configured](https://help.socure.com/riskos/docs/webhooks). Test event delivery and review logs for failures. |
| Unexpected results in Production | Integration was not validated in Sandbox before going live | Use Sandbox with test data to validate all flows before switching to Production. |
| Persistent errors | Issue remains after basic troubleshooting | Contact [Socure Support](mailto:support@socure.com) with error messages, request `id`, `eval_id`, and logs. |

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