## How RiskOS™ works

RiskOS™ is a configurable identity orchestration and decisioning platform. You send data about a person, business, or device. RiskOS™ runs it through a workflow of verification checks, rules, and scoring logic, then returns a decision — `ACCEPT`, `REJECT`, or `REVIEW` — with enrichment data, risk scores, and reason codes.

Every RiskOS™ interaction follows the same runtime chain:

```
API Request
Evaluation
Workflow
Enrichments
Rules & Scoring
Decision
```

1. Your application sends a `POST` to the [Evaluation API](https://help.socure.com/riskos/docs/integrating-with-riskos) with user data and a workflow name.
2. An evaluation starts and executes the selected workflow.
3. The workflow calls enrichments, generates signals, evaluates rules, and computes scores.
4. The workflow returns a decision: `ACCEPT`, `REJECT`, or `REVIEW`.

Some evaluations complete immediately (synchronous). Others pause for user action and deliver results via webhook (asynchronous). See [Synchronous vs Asynchronous Evaluations](https://help.socure.com/riskos/docs/sync-vs-async-evaluations) for more information.

## Core concepts

RiskOS™ automates identity verification, fraud prevention, and compliance through six interconnected building blocks. The sections below define each concept, explain its purpose, and show how they relate to each other.

| Concept | What it is |
| --- | --- |
| [**Evaluation**](https://help.socure.com/riskos/docs/understanding-riskos#evaluations) | A single execution of a workflow — the runtime unit of work |
| [**Workflow**](https://help.socure.com/riskos/docs/understanding-riskos#workflows) | A configurable sequence of steps that processes an evaluation |
| [**Enrichment**](https://help.socure.com/riskos/docs/understanding-riskos#enrichments) | A data service that adds risk, identity, or compliance signals |
| [**Signals & Attributes**](https://help.socure.com/riskos/docs/understanding-riskos#signals--attributes) | The data taxonomy: inputs, enrichment outputs, reason codes, tags, and derived values |
| [**Rules & Conditions**](https://help.socure.com/riskos/docs/understanding-riskos#rules--conditions) | The logic layer that evaluates signals and routes the workflow |
| [**Decision**](https://help.socure.com/riskos/docs/understanding-riskos#decisions) | The final outcome: `ACCEPT`, `REJECT`, or `REVIEW` |

### How these concepts work together

The six concepts form a processing pipeline. Each feeds into the next, transforming raw input data into a risk decision.

```
API Request
Attributes (input)
Input Step validates payload
Enrichment Steps call data services
Signals returned
Reason Codes returned
Transformation Steps
Derived Values
Rules & Conditions evaluate data
Tag Steps classify evaluation
Tags
Decision Step assigns outcome
API Response
```

#### The processing sequence

1. **Your application submits attributes.** A `POST /api/evaluation` request sends PII (name, DOB, SSN, email, phone, device data) and specifies which workflow to run.
2. **The evaluation starts.** RiskOS™ assigns an `eval_id` and begins executing the workflow.
3. **The workflow processes data through steps.** The Input step validates the payload. Enrichment steps call data services and return signals — scores, match results, and risk flags.
4. **Rules and conditions evaluate the signals.** Condition steps branch the workflow based on signal values. Rule Scorecards compute aggregate risk scores. Decision Rules map conditions to outcomes.
5. **The workflow reaches a terminal step.** A Decision step assigns `ACCEPT`, `REJECT`, or `REVIEW`. A Manual Review step routes the evaluation to [Case Management](https://help.socure.com/riskos/docs/cases-and-manual-review) for human assessment.
6. **RiskOS™ returns the result.** The API response (or webhook for async evaluations) includes the decision, enrichment data, reason codes, tags, and computed values.

## Evaluations

An **evaluation** is a single execution of a [workflow](https://help.socure.com/riskos/docs/understanding-riskos#workflows) in RiskOS™. When your application sends a `POST` request to the `/api/evaluation` endpoint with user, business, or device data, RiskOS™ runs the specified workflow and returns a [decision](https://help.socure.com/riskos/docs/understanding-riskos#decisions) along with enrichment data, risk scores, and reason codes.

Every interaction with the RiskOS™ decisioning engine — whether identity verification, fraud screening, or compliance check — is an evaluation.

### Evaluation lifecycle

| Phase | What happens | Output |
| --- | --- | --- |
| **Request** | Your application sends a `POST` to `/api/evaluation` with a payload containing PII and a workflow name | `eval_id` assigned |
| **Execution** | RiskOS™ runs the workflow: Input → Enrichments → Conditions → Rules → Decision | Step-by-step processing |
| **Decision** | The workflow reaches a terminal step (Decision or Manual Review) | `ACCEPT`, `REJECT`, or `REVIEW` |
| **Response** | RiskOS™ returns the decision, enrichment data, tags, reason codes, and scores | JSON response or webhook |

Evaluations can execute **synchronously** (completing in a single API response) or **asynchronously** (pausing for user action and delivering results via webhook). See [Synchronous vs Asynchronous Evaluations](https://help.socure.com/riskos/docs/sync-vs-async-evaluations) for the full execution model.

## Workflows

A **workflow** is a configurable sequence of steps that automates decision-making in RiskOS™. When an [evaluation](https://help.socure.com/riskos/docs/understanding-riskos#evaluations) is triggered, RiskOS™ executes the specified workflow — processing data through input collection, enrichment calls, conditional logic, and rules — to reach a final [decision](https://help.socure.com/riskos/docs/understanding-riskos#decisions).

You build workflows visually in the RiskOS™ Dashboard using the Workflow Editor.

### What a workflow does

A workflow defines:

1. **What data to accept** — The Input step specifies required fields in the evaluation payload.
2. **What data services to call** — Enrichment steps call Socure products or third-party APIs for additional [signals](https://help.socure.com/riskos/docs/understanding-riskos#signals--attributes).
3. **How to evaluate the data** — Condition steps, Rule Scorecards, and Transformation steps apply logic to route and score data.
4. **What decision to return** — A Decision step or Manual Review step terminates the workflow with an outcome.

### Custom workflows vs Hosted Flows

RiskOS™ supports two workflow delivery models. Both use the same evaluation runtime, enrichment pipeline, and decision model.

| Aspect | Custom workflow | Hosted Flow |
| --- | --- | --- |
| **Configuration** | Built and managed by the customer in the Workflow Editor | Preconfigured with a Socure-managed end-user UI |
| **End-user UI** | Customer-built (API + SDK) | Socure-hosted (web-based) |
| **Extensibility** | Full — any step type, any enrichment, any rule | Template customization and branding |

Both categories produce [evaluations](https://help.socure.com/riskos/docs/understanding-riskos#evaluations), return [decisions](https://help.socure.com/riskos/docs/understanding-riskos#decisions), and follow the same [lifecycle states](https://help.socure.com/riskos/docs/statuses-and-lifecycle). The distinction is operational — ownership and configuration model — not architectural.

## Decisions

A **decision** is the final outcome of an [evaluation](https://help.socure.com/riskos/docs/understanding-riskos#evaluations). It represents the platform's determination — based on [enrichment](https://help.socure.com/riskos/docs/understanding-riskos#enrichments) data, [rules](https://help.socure.com/riskos/docs/understanding-riskos#rules--conditions), and scoring logic — of whether to accept, reject, or flag an entity for further review.

Terminal [workflow](https://help.socure.com/riskos/docs/understanding-riskos#workflows) steps assign decisions: a **Decision** step for automated outcomes, or a **Manual Review** step for human review.

### Decision values

The Evaluation API returns three standard decision values:

| Value | Meaning | Typical action |
| --- | --- | --- |
| `ACCEPT` | The entity passed all checks | Proceed with onboarding, transaction, or access |
| `REJECT` | The entity failed one or more checks | Deny the request |
| `REVIEW` | The evaluation requires human assessment | Route to [Case Management](https://help.socure.com/riskos/docs/cases-and-manual-review) for manual review |

## Enrichments

An **enrichment** is a data service that supplements an [evaluation](https://help.socure.com/riskos/docs/understanding-riskos#evaluations) with additional risk, identity, and compliance [signals](https://help.socure.com/riskos/docs/understanding-riskos#signals--attributes) beyond the data provided in the initial API request. Enrichments are also referred to as **products** in the RiskOS™ platform.

During [workflow](https://help.socure.com/riskos/docs/understanding-riskos#workflows) execution, an **Enrichment step** calls a Socure product or third-party API to retrieve structured data — scores, reason codes, attributes, and validation results. The workflow then uses these signals in downstream [rules and conditions](https://help.socure.com/riskos/docs/understanding-riskos#rules--conditions) to reach a [decision](https://help.socure.com/riskos/docs/understanding-riskos#decisions).

### How enrichments work

```
Data ServiceRiskOS™Your ApplicationData ServiceRiskOS™Your ApplicationPOST /api/evaluation (PII + workflow)Run Input stepCall enrichment (e.g., Phone Risk)Return scores, reason codes, attributesApply rules using enrichment signalsReach decisionReturn decision + data_enrichments[]
```

1. The workflow reaches an Enrichment step.
2. RiskOS™ calls the configured data service with the relevant payload fields.
3. The service returns structured results (scores, codes, attributes).
4. RiskOS™ stores the results in the `data_enrichments` array of the evaluation response.
5. Downstream steps (Conditions, Rule Scorecards, Decisions) reference these results.

### Enrichment categories

| Category | Enrichments | What they provide |
| --- | --- | --- |
| **Identity verification** | Verify, Verify Plus, Prefill, eCBSV, Deceased Check | KYC data, SSN verification, identity attributes |
| **Document verification** | Predictive DocV | Government ID capture and verification |
| **Device & behavioral** | Digital Intelligence, Account Intelligence | Device fingerprinting, behavioral signals, bank account verification |
| **Fraud detection** | Sigma Identity Fraud, Sigma Synthetic Fraud, Sigma First-Party Fraud | ML-based fraud scores and reason codes |
| **Risk scoring** | Address Risk, Email Risk, Phone Risk, Graph Intelligence | PII attribute risk scores and identity correlation |
| **Compliance** | Watchlist | Sanctions, PEP, and adverse media screening |
| **User verification** | OTP, CNAM | Contact information verification |
| **Partner** | Partner Ecosystem | Third-party data services |

### Enrichments vs signals

| Concept | Scope | Example |
| --- | --- | --- |
| **Enrichment** | The data service that the workflow calls | Sigma Identity Fraud |
| **Signal** | A discrete data point returned by an enrichment | `sigma_identity_fraud.score = 0.92` |

An enrichment produces multiple signals. Signals are the inputs to [rules and conditions](https://help.socure.com/riskos/docs/understanding-riskos#rules--conditions).

## Rules & Conditions

**Rules** and **conditions** are the logic layer in RiskOS™ [workflows](https://help.socure.com/riskos/docs/understanding-riskos#workflows). They evaluate [signals](https://help.socure.com/riskos/docs/understanding-riskos#signals--attributes) from [enrichments](https://help.socure.com/riskos/docs/understanding-riskos#enrichments), input data, and computed values to determine how to route an [evaluation](https://help.socure.com/riskos/docs/understanding-riskos#evaluations) and which [decision](https://help.socure.com/riskos/docs/understanding-riskos#decisions) to assign.

### Conditions

A **condition** evaluates one or more expressions to `true` or `false` and branches the workflow accordingly. Each expression compares a left operand (such as an enrichment score) against a right operand (such as a threshold value) using an operator (such as `greater than`).

Conditions can be grouped using **AND** (all must be true) or **OR** (at least one must be true). The workflow follows the **True** path if the condition group evaluates to true, and the **False** path otherwise.

### Rule types

RiskOS™ uses the term "rule" in several workflow step contexts. Each serves a different purpose:

| Rule type | Step | Purpose | Output |
| --- | --- | --- | --- |
| **Condition rule** | Condition | Routes the workflow based on boolean logic | True/False branch |
| **Score rule** | Rule Scorecard | Assigns a numeric risk score (-100 to 100) when a condition is met | Summed score value |
| **Decision rule** | Decision Rules | Combines a condition with a decision outcome in a single step | `ACCEPT`, `REJECT`, `REVIEW`, custom values, or Manual Review |
| **Matrix rule** | Matrix Rule | Evaluates a tabular set of conditions | Row-level match |
| **Grouped rules** | Grouped Rules | Evaluates collections of related rules together | Group-level outcome |

### How conditions and rules drive decisions

```
True

False

Yes

No

Rule 1 match

No match

Enrichment signals

Condition step

Rule Scorecard

Decision Rules

Score > threshold?

Decision: ACCEPT

Decision: REVIEW

Decision: REJECT

Fallback: continue
```

## Signals & Attributes

RiskOS™ [workflows](https://help.socure.com/riskos/docs/understanding-riskos#workflows) process five distinct types of data during an [evaluation](https://help.socure.com/riskos/docs/understanding-riskos#evaluations). Each has a precise definition, a distinct runtime role, and a specific location in the API response.

### Data taxonomy

| Term | Definition | Set by | API response location |
| --- | --- | --- | --- |
| **Attribute** | A normalized input field describing the entity being evaluated | Your application (via API request) | Request payload (`data.*`) |
| **Signal** | A discrete data point returned by an enrichment or external data service | Enrichment step | `data_enrichments[].response.*` |
| **Reason code** | A human-readable code explaining why a specific outcome occurred | Enrichment response or Reason Code step | `data_enrichments[].response.reason_codes[]` |
| **Tag** | A metadata label conditionally attached to an evaluation | Tag step | `tags[]` |
| **Derived value** | A value computed by a workflow step from attributes, signals, or other derived values | Transformation or Rule Scorecard step | `computed.*` |

**Attributes** are the input data your application sends — name, DOB, SSN, email, phone, device data, and custom fields. The Input step of a workflow defines which attributes are required and optional.

**Signals** are the evidence used by rules and conditions to reach a decision. Each enrichment produces multiple signals — risk scores, match results, fraud flags, and validation results.

**Reason codes** provide explainability. They answer "why did this evaluation receive this decision?" Reason codes are decision _explanations_, not decision inputs.

**Tags** classify evaluations for operational purposes — filtering cases, triggering automation, and segmenting analytics. Tag steps assign tags when their conditions evaluate to `true`.

**Derived values** are intermediate computations produced by Transformation steps and Rule Scorecards. They feed into downstream rules and conditions.