What is an Evaluation?
Learn the evaluation lifecycle — from API request through workflow execution to a final accept, reject, or review decision.
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
| 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 |
| Case creation (conditional) | If the workflow routes to Manual Review, the evaluation creates a case in Case Management | Case record |
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.
eval_status value | Description | Trigger |
|---|---|---|
evaluation_in_progress | The workflow is actively executing steps | POST /api/evaluation received and workflow starts |
evaluation_paused | The workflow is waiting for user action (OTP, DocV, Wait step, Hosted Flow) | Asynchronous step reached |
evaluation_completed | The workflow ran to completion and returned a decision | All steps executed |
Webhook events such as workflow_execution_failed indicate additional terminal outcomes. You can also terminate a paused evaluation via PATCH /api/evaluation/{eval_id} with actions.end.
For the full lifecycle model — including workflow states, case statuses, and state diagrams — see Statuses & Lifecycle.
Key fields in the evaluation response
| Field | Type | Description |
|---|---|---|
eval_id | string | Unique identifier for this evaluation |
workflow_name | string | The workflow that processed the evaluation |
decision | string | Final outcome: ACCEPT, REJECT, or REVIEW |
tags | array | Metadata labels applied by Tag steps during execution |
reason_codes | array | Codes explaining why the decision was reached |
data_enrichments | array | Results from each enrichment called during execution |
computed | object | Values calculated by Transformation and Rule Scorecard steps |
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_pausedstatus. When the action completes, the workflow resumes and delivers the final result via webhook.
See Synchronous vs Asynchronous Evaluations for the full execution model.
Related concepts
- Workflows — The logic that processes an evaluation
- Decisions — The possible outcomes of an evaluation (distinct from evaluation states)
- Statuses & Lifecycle — Full lifecycle model: evaluation states, workflow states, case statuses
- Signals & Attributes — The data that flows into and out of an evaluation
- Cases & Manual Review — How evaluation results are reviewed
- Enrichments — Data services called during evaluation execution
- Synchronous vs Asynchronous Evaluations — Execution patterns
- Hosted Flows — A workflow delivery model that creates asynchronous evaluations
- Terminology Governance — "Evaluation" not "transaction" or "request"
- Resuming Paused Evaluations — How to resume an async evaluation via API
- API Reference: POST /api/evaluation — Request and response specification
Updated 5 days ago