## How to interpret the response

After creating an evaluation, use the response to determine how your application should route the user and continue the verification flow.

Your integration should not rely on a single field. Always evaluate `decision` + `status` + `sub_status` + `tags` together when determining next steps.

- `decision` → High-level outcome (`ACCEPT`, `REJECT`, `REVIEW`)
- `status` → Whether the evaluation is complete (`CLOSED`, `ON_HOLD`)
- `sub_status` → The current verification state (for example, `Awaiting Customer OTP` or `More information needed`)
- `tags` → Why the evaluation reached this decision and what action to take next

## Evaluation flow

This workflow evaluates users in stages:

1. **Digital Intelligence (device risk)**

Detects high-risk device and network signals.

2. **Phone Risk and One-Time Passcode (OTP) step-up**

If the phone requires verification, RiskOS™ pauses the evaluation and sends an OTP.

3. **Prefill**

After the user approves the OTP, RiskOS™ attempts to retrieve prefill data.

4. **Additional identity data**

If more information is required, your application must collect the user's full identity data and continue the evaluation.

5. **Final screening**

RiskOS™ completes checks before returning a terminal decision.

If no blocking risks are found, the evaluation completes. Otherwise, it may:
   - **Reject immediately**, or
   - **Pause for OTP or additional identity data**

## Decision outcomes

| Decision | Status | Meaning | Action |
| --- | --- | --- | --- |
| `ACCEPT` | `CLOSED` | The evaluation completed successfully. | Continue onboarding. |
| `REJECT` | `CLOSED` | The user failed a critical risk or verification check. | Stop or route to fallback. |
| `REVIEW` | `ON_HOLD` | Additional verification or identity data is required. | Continue the verification flow (OTP or identity collection). |

## Outcome handling

### `REVIEW` — One-Time Passcode required

The evaluation is paused while the user completes OTP verification.

Key signals:

- `decision: "REVIEW"`
- `status: "ON_HOLD"`
- `sub_status: "Awaiting Customer OTP"`
- `tags` contains `OTP Triggered`

**What to do**:
- Prompt the user to enter the OTP.
- Submit the code using `PATCH /api/evaluation/{eval_id}`.
- Continue the evaluation after OTP is verified.

### `REVIEW` — Additional identity data required

After OTP verification, the evaluation may still require additional identity data.

Key signals:

- `decision: "REVIEW"`
- `status: "ON_HOLD"`
- `sub_status: "More information needed"`
- `tags` contains `Additional PII Requested`

**What to do**:
- If `Prefill Successful`, display prefilled data to the user
- If `Prefill Unsuccessful`, collect identity data manually
- Submit data using `PATCH /api/evaluation/{eval_id}`

### `ACCEPT`

The evaluation completed successfully and the user passed the workflow checks.

**What to do**:
- Continue onboarding.
- Grant access or create the account.

### `REJECT`

The user failed a critical risk or verification check.

Common reject patterns in this workflow include:
- High-risk or unsupported phone signals
- Failed Verify checks
- SSN mismatch
- Watchlist hit

**What to do**:
- Stop onboarding.
- Route to a fallback, manual review, or decline flow.

## Common routing signals

Use the response fields together to decide the next step.

| Signals | Meaning | What to do |
| --- | --- | --- |
| `REVIEW` + `ON_HOLD` + `Awaiting Customer OTP` + `OTP Triggered` | The user must complete OTP verification. | Prompt for OTP and patch the evaluation. |
| `REVIEW` + `ON_HOLD` + `More information needed` + `Additional PII Requested` + `Prefill Successful` | Prefill data is available, but more identity data is still required. | Display approved prefill data and collect remaining fields. |
| `ACCEPT` + `CLOSED` | Final accept. | Continue onboarding. |
| `REJECT` + `CLOSED` | Final reject. | Stop or route to fallback. |

## Error handling

If the API returns an HTTP error, your application should handle it before processing any evaluation logic.

| Status code | Meaning | What to do |
| --- | --- | --- |
| `400` | Bad request — missing or invalid fields | Check request body against required fields. |
| `401` | Unauthorized — invalid or missing API key | Verify your `Authorization` header. |
| `404` | Not found — invalid `eval_id` or endpoint | Confirm the `eval_id` and endpoint URL. |
| `429` | Rate limited | Back off and retry. |
| `500` | Internal server error | Retry with exponential backoff. |

## Persist evaluation state

Store these fields so your application can resume and route the evaluation correctly:
- `id`
- `eval_id`
- `decision`
- `status`
- `sub_status`
- `tags`
- `workflow` (optional)

## Key takeaways

- Use `decision` + `status` + `sub_status` + `tags` together.
- `REVIEW` means the evaluation is paused, not complete.
- `OTP Triggered` means your application should collect and submit an OTP.
- `Additional PII Requested` means your application must collect more identity data.
- `Prefill Successful` does not necessarily mean final acceptance.
- `ACCEPT` and `REJECT` are terminal outcomes in this workflow.