Understanding RiskOS™

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:

flowchart LR
    A[API Request] --> B[Evaluation]
    B --> C[Workflow]
    C --> D[Enrichments]
    D --> E[Rules & Scoring]
    E --> F[Decision]

1. Your application sends a POST to the Evaluation API 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 for more information.

Explore RiskOS™

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.

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.

flowchart TD
    REQ["API Request"] --> ATTR["Attributes (input)"]
    ATTR --> INPUT["Input Step validates payload"]
    INPUT --> ENRICH["Enrichment Steps call data services"]
    ENRICH --> SIG["Signals returned"]
    ENRICH --> RC["Reason Codes returned"]
    INPUT --> TRANSFORM["Transformation Steps"]
    TRANSFORM --> DV["Derived Values"]
    SIG --> RULES["Rules & Conditions evaluate data"]
    DV --> RULES
    RULES --> TAG["Tag Steps classify evaluation"]
    TAG --> TAGS["Tags"]
    RULES --> DECISION["Decision Step assigns outcome"]
    SIG --> RESP["API Response"]
    RC --> RESP
    TAGS --> RESP
    DV --> RESP
    DECISION --> RESP

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

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 for the full execution model.

For evaluation states, case creation, and lifecycle diagrams, see Statuses & Lifecycle. For the API request and response specification, see POST /api/evaluation.

Workflows

A workflow is a configurable sequence of steps that automates decision-making in RiskOS™. When an evaluation is triggered, RiskOS™ executes the specified workflow — processing data through input collection, enrichment calls, conditional logic, and rules — to reach a final decision.

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

Both categories produce evaluations, return decisions, and follow the same lifecycle states. The distinction is operational — ownership and configuration model — not architectural.

For step-level configuration, see Workflow Steps Reference. For lifecycle management, see Manage Workflow Lifecycle. For the full Hosted Flow ontology, see Hosted Flows.

Decisions

A decision is the final outcome of an evaluation. It represents the platform's determination — based on enrichment data, rules, and scoring logic — of whether to accept, reject, or flag an entity for further review.

Terminal workflow 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:

Decision Rules steps can also assign custom values such as RESUBMIT and CANCEL, or route to Manual Review.

Two types of decisions

Automated decisions — A Decision step or Decision Rules step in the workflow assigns the outcome. The evaluation API response returns the decision without human involvement.

Manual review decisions occur when a workflow routes to a Manual Review step. The evaluation enters Case Management, where a human reviewer makes the final determination. RiskOS™ communicates the reviewer's decision via webhook (decision_update event) or API polling.

For the full lifecycle model — including the relationship between decisions, evaluation states, and case statuses — see Statuses & Lifecycle.

Enrichments

An enrichment is a data service that supplements an evaluation with additional risk, identity, and compliance signals beyond the data provided in the initial API request. Enrichments are also referred to as products in the RiskOS™ platform.

During workflow 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 to reach a decision.

How enrichments work

sequenceDiagram
    participant App as Your Application
    participant RiskOS as RiskOS™
    participant Svc as Data Service

    App->>RiskOS: POST /api/evaluation (PII + workflow)
    RiskOS->>RiskOS: Run Input step
    RiskOS->>Svc: Call enrichment (e.g., Phone Risk)
    Svc-->>RiskOS: Return scores, reason codes, attributes
    RiskOS->>RiskOS: Apply rules using enrichment signals
    RiskOS->>RiskOS: Reach decision
    RiskOS-->>App: Return 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

Enrichments vs signals

An enrichment produces multiple signals. Signals are the inputs to rules and conditions. To learn how to read an enrichment's score and the reason codes returned alongside it, see Reason Codes & Score Interpretation.

For the complete enrichment catalog, see Enrichments Overview. For error handling, see Enrichment Error Handling.

Rules & Conditions

Rules and conditions are the logic layer in RiskOS™ workflows. They evaluate signals from enrichments, input data, and computed values to determine how to route an evaluation and which decision 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:

How conditions and rules drive decisions

flowchart TD
    ENRICH["Enrichment signals"] --> COND["Condition step"]
    COND -->|True| SCORE["Rule Scorecard"]
    COND -->|False| DR["Decision Rules"]
    SCORE --> THRESHOLD{"Score > threshold?"}
    THRESHOLD -->|Yes| ACCEPT["Decision: ACCEPT"]
    THRESHOLD -->|No| REVIEW["Decision: REVIEW"]
    DR -->|Rule 1 match| REJECT["Decision: REJECT"]
    DR -->|No match| FALLBACK["Fallback: continue"]

Signals & Attributes

RiskOS™ workflows process five distinct types of data during an evaluation. Each has a precise definition, a distinct runtime role, and a specific location in the API response.

Data taxonomy

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.

For entity tracking and aggregation functions, see Entities and Aggregations.

Common integration patterns

Explore solutions

RiskOS™ supports identity verification, fraud prevention, compliance, business verification, and onboarding use cases.

Related topics

• Hosted Flows — Preconfigured workflows with Socure-managed UI
• Step-up Verification — Conditional escalation to higher-assurance checks
• Cases & Manual Review — How human reviewers handle REVIEW decisions
• Synchronous vs Asynchronous Evaluations — Execution patterns for real-time and deferred workflows
• Statuses & Lifecycle — Full lifecycle model with state diagrams for evaluations, workflows, and cases
• Terminology — Canonical naming conventions for RiskOS™ platform concepts
• Enrichments Overview — Full enrichment catalog with integration guides
• Workflow Steps Reference — Step-level configuration and field definitions
• API Reference: POST /api/evaluation — Request and response specification