Core Concepts

RiskOS™ automates identity verification, fraud prevention, and compliance through six interconnected concepts. Understanding how these concepts relate to each other is essential for building effective integrations.

flowchart LR
    A[Input] --> B[Evaluation]
    B --> C[Workflow]

    C --> D[Enrichments]
    D --> E[Signals]

    E --> F[Rules]
    F --> G[Decision]

---

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

Evaluation states

The eval_status field tracks where an evaluation is in execution. These states are distinct from decisions, which track what action to take.

Webhook events such as workflow_execution_failed indicate additional terminal outcomes. You can also update a paused evaluation's state — including setting a final decision — via PUT /api/evaluation/{eval_id}/state.

For the full lifecycle model — including workflow states, case statuses, and state diagrams — see Statuses & Lifecycle.

Key fields in the evaluation response

Synchronous vs asynchronous evaluations

Evaluations follow one of two execution patterns depending on the workflow configuration:

• Synchronous: The workflow completes all steps and returns a decision in the API response. This is the default for workflows without user-interaction steps.
• Asynchronous: The workflow pauses at a step that requires user action (Document Verification, OTP, or a Wait step). RiskOS™ returns an evaluation_paused status. When the action completes, the workflow resumes and delivers the final result via webhook.

See Synchronous vs Asynchronous Evaluations for the full execution model.

---

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.

Workflow categories

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 the full Hosted Flow ontology, see Hosted Flows.

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.

Step types

Every workflow consists of steps. Each step has a single purpose:

For step-level configuration and field definitions, see Workflow Steps Reference.

Workflow lifecycle

Workflows move through three states:

A workflow must be Published before it can be set to Live. Only one version of a workflow can be Live at a time.

Versioning:

• Major version: Duplicate a published workflow to create a new independent version.
• Minor version: Edit a published workflow to create a patch (available only for certain changes).

For lifecycle management details, see Manage Workflow Lifecycle.

Workflow modes

Terminal steps

Every workflow must end with one of:

• A Decision step — assigns an automated outcome
• A Manual Review step — routes to a human reviewer

A workflow without a terminal step can't be published.

---

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.

Decisions are set by terminal workflow steps: a Decision step for automated outcomes, or a Manual Review step for human review.

Decision values

The Evaluation API returns three standard decision values:

Custom and step-level values: Decision Rules steps can also assign values such as RESUBMIT and CANCEL, or route to Manual Review. You can define additional custom decision values when configuring a Decision step or Decision Rules step. These values appear in the API response and Case Management alongside the standard values.

Two types of decisions

Automated decisions are set by a Decision step or Decision Rules step in the workflow. These are returned in the evaluation API response without human involvement.

Manual review decisions occur when a workflow routes to a Manual Review step. The evaluation enters Case Management. A human reviewer examines the case and makes a final decision — typically Accept or Reject. The reviewer's decision is communicated back to your system via webhook (decision_update event) or API polling.

Where decisions appear

Decision vs status vs evaluation state

Decisions, statuses, and evaluation states are three distinct runtime concepts:

A case can have a REVIEW decision, an Open status with an "In Review" sub-status, and an evaluation_completed evaluation state simultaneously — each tracks a different dimension.

For the full lifecycle model with state diagrams, 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. Results are stored in the data_enrichments array of the evaluation response.
5. Downstream steps (Conditions, Rule Scorecards, Decisions) reference these results.

Where enrichment results appear in the API

Enrichment results are returned in the data_enrichments array of the evaluation response. Each entry represents a single enrichment call:

Enrichment categories

For the complete enrichment catalog with integration guides, see Enrichments Overview.

Enrichment error handling

If an enrichment call fails, RiskOS™ retries automatically. On final failure:

• The enrichment output is set to null.
• Downstream Condition steps referencing the failed enrichment evaluate to false.
• You can configure fallback Enrichment steps to chain alternative providers.

For error handling details, see Enrichment Error Handling.

Enrichments vs signals

An enrichment produces multiple signals. Signals are the inputs to rules and conditions.

---

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 an evaluation is routed and what decision is reached.

Conditions

A condition evaluates one or more expressions to true or false and branches the workflow accordingly.

Condition structure:

Each condition expression has three parts:

Operand sources:

Operators:

Grouping:

Combine multiple conditions using:

• AND — all conditions must be true
• OR — at least one condition 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 Scorecards

A Rule Scorecard assigns numeric risk scores based on rule evaluations:

1. Each score rule defines a condition and a score value (-100 to 100).
2. Rules that evaluate to true contribute their score.
3. The final output is the sum of all matching scores.
4. Downstream Condition or Decision steps reference the scorecard output to make routing decisions.

Decision Rules

A Decision Rules step combines condition evaluation with decision assignment in a single step:

• Each rule maps a condition to an outcome — the standard API decision values (ACCEPT, REJECT, REVIEW), step-level values (RESUBMIT, CANCEL), or Manual Review routing.
• Rules are evaluated top-to-bottom; the first matching rule applies.
• A fallback (Else) path handles cases where no rule matches — it can either continue without a decision or assign a default decision.

This is the only workflow step that can both issue a final decision and continue execution via a fallback path.

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

An attribute is an input data point about the entity being evaluated — the information your application sends in the POST /api/evaluation request.

The Input step of a workflow defines which attributes are required and optional. Attributes are available to all downstream steps as operands in conditions and rules.

Signals

A signal is a discrete data point returned by an enrichment during workflow execution. Signals are the primary evidence used by rules and conditions to reach a decision.

Signals appear in data_enrichments[].response.* in the evaluation API response.

Reason codes

A reason code is a human-readable identifier explaining a specific factor in an enrichment result or decision outcome. Reason codes provide explainability — they answer "why did this evaluation receive this decision?"

Reason codes are not decision inputs — they are decision explanations. Rules and conditions evaluate signals, not reason codes (though the has reason code operator enables reason-code-aware routing).

Tags

A tag is a metadata label conditionally attached to an evaluation by a Tag step in the workflow. Tags classify evaluations for operational purposes.

Tags are metadata, not decision inputs. They describe the evaluation after the fact, enabling downstream filtering and reporting.

Derived values

A derived value is a value computed during workflow execution from attributes, signals, or other derived values. Derived values are intermediate computations used by downstream rules and conditions.

Derived values appear in the computed object of the API response (requires feature flag) and are referenced in downstream steps using the $output_field_name syntax.

Entities and aggregations

RiskOS™ tracks certain attributes as entities — core data elements that represent a real-world actor (email address, phone number, SSN, account UUID). Entities enable:

• Aggregation features: Computations applied across evaluations sharing the same entity (count, average, sum, min, max, first seen, last seen, distinct count).
• Time windows: Aggregations can be scoped to specific periods (minutes, hours, days, or lifetime).
• Cross-journey linkage: The same entity connects evaluations across onboarding, authentication, and fraud review via SocureID.

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

---

How These Concepts Work Together

The six concepts above form a processing pipeline. Each concept feeds into the next, and together they transform raw input data into a risk decision.

End-to-end data flow

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. The evaluation state is evaluation_in_progress.

3. The workflow processes data through steps. The Input step validates the payload. Enrichment steps call data services (Sigma Fraud, Phone Risk, Watchlist, DocV, and others) 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, all enrichment data, reason codes, tags, and computed values.

Concept relationships

---

Related topics

These concepts are covered in dedicated pages for deeper reference:

• Hosted Flows — Preconfigured workflows with Socure-managed UI
• Step-up Verification — Conditional escalation to higher-assurance checks
• Cases & Manual Review — How REVIEW decisions are handled by human reviewers
• 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