RiskOS™ [evaluations](https://help.socure.com/riskos/docs/understanding-riskos#evaluations) follow one of two execution patterns depending on the [workflow](https://help.socure.com/riskos/docs/understanding-riskos#workflows) configuration: **synchronous** (immediate response) or **asynchronous** (paused for user action, results via webhook).

## Comparison

| Aspect | Synchronous | Asynchronous |
| --- | --- | --- |
| **Response** | [Decision](https://help.socure.com/riskos/docs/understanding-riskos#decisions) returned in the API response | `evaluation_paused` status returned; decision delivered via webhook |
| **Workflow steps** | No user-interaction steps (OTP, DocV, Wait, Hosted Flow) | Contains at least one user-interaction step |
| **Typical use cases** | Identity verification, fraud screening, risk scoring | Document verification, OTP challenges, multi-step onboarding |
| **Webhook required** | Optional (for case updates, watchlist alerts) | Required (for receiving the final decision) |
| **Latency** | Milliseconds to seconds | Seconds to hours (depends on user action) |

## Synchronous execution

```
RiskOS™Your ApplicationRiskOS™Your ApplicationPOST /api/evaluationInput → Enrichments → Rules → Decision200 OK (decision + enrichment data)
```

The workflow completes all steps in a single request-response cycle. The API returns the [decision](https://help.socure.com/riskos/docs/understanding-riskos#decisions), [enrichment](https://help.socure.com/riskos/docs/understanding-riskos#enrichments) data, tags, reason codes, and scores.

### When workflows are synchronous

A workflow is synchronous when it contains **no user-interaction steps**. All enrichment calls, conditions, transformations, and decisions execute server-side without requiring input from the end user.

## Asynchronous execution

```
End UserRiskOS™Your ApplicationEnd UserRiskOS™Your ApplicationPOST /api/evaluationInput → Enrichments → ...Reach async step (OTP / DocV / Wait / Hosted Flow)200 OK (evaluation_paused + eval_id)Prompt for actionComplete action (verify OTP, capture document, etc.)Resume → remaining steps → DecisionWebhook: evaluation_completed (decision + data)
```

The workflow pauses when it reaches a step that requires user action. RiskOS™ returns a response with `evaluation_paused` status and the `eval_id`. When the user completes the action, the workflow resumes and delivers the final decision via webhook.

### Steps that make a workflow asynchronous

| Step | What it waits for |
| --- | --- |
| **OTP** | User enters a one-time passcode sent via SMS, voice, or email |
| **DocV (Predictive Document Verification)** | User captures a government-issued ID (and optional selfie) |
| **Wait** | An external API `PATCH` call resumes the workflow |
| **Hosted Flow** | User completes a Socure-hosted data collection or verification page |

## Handling paused evaluations

When an evaluation pauses, your application should:

1. **Store the `eval_id`** from the initial API response.
2. **Direct the user** to complete the required action (redirect to Hosted Flow URL, launch DocV SDK, or prompt for OTP).
3. **Listen for webhooks**: Subscribe to `evaluation_completed` and `evaluation_paused` events.
4. **Process the final decision** from the webhook payload.

### Updating a paused evaluation

To supply additional data to a paused evaluation (for example, after the user provides missing PII), send a `PATCH` request to `/api/evaluation/{eval_id}` with the updated fields. The request body follows the same structure as the original `POST` request. Once the paused step's requirements are met, the workflow resumes automatically.

### Setting a decision on a paused evaluation

To end a paused evaluation with a specific decision, send a `PUT` request to `/api/evaluation/{eval_id}/state`:

```bash
PUT /api/evaluation/{eval_id}/state
{
  "workflow": "your_workflow_name",
  "decision": "REJECT"
}
```

This sets the evaluation's decision and closes it without resuming the remaining workflow steps.

## Webhook events for async evaluations

| Event | When it fires |
| --- | --- |
| `evaluation_paused` | Workflow reaches an async step and pauses |
| `evaluation_completed` | Workflow resumes, completes, and returns a final decision |
| `workflow_execution_failed` | Workflow encounters an unrecoverable error during execution |

> **Important**: Evaluation webhook events are sent **only** for asynchronous workflows. If your workflows don't contain async steps, you won't receive these events. Subscribe to `decision_update` and case events for post-decision notifications.