Handle Results

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

Interpret the response

The response determines how your application should proceed.

If the workflow returns ON_HOLD, inspect response tags and sub_status to determine the next step.

📘

Note:

Do not route based on status alone. Use decision, sub_status, and tags together to determine the next step.

For the full response schema and all available fields, see the Evaluation API Reference.

How decisions are determined

RiskOS™ evaluates device, identity, and fraud signals in stages.

The evaluation begins with Digital Intelligence (device risk). If high-risk signals are detected (such as bots, emulators, or high-risk VPNs), RiskOS™ may return a REJECT decision immediately.

If the evaluation passes initial checks, RiskOS™ continues with identity verification and enrichment.

Decision outcomes

👍

Tip:

Use the tags field in the response to understand why a decision was made and how to route the user.

Possible outcomes

POST /evaluation
  ├── REJECT → Stop onboarding
  ├── REVIEW → Additional verification required
  │      ├── One-Time Passcode required
  │      └── Additional PII required
  └── ACCEPT → Prefill available

Response handling

Response notes

• One-Time Passcode failure results in REJECT, not another ON_HOLD state.
• Prefill may succeed or fail; handle both scenarios.
• DocV is triggered from multiple step-up conditions across fraud, identity, and risk signals.

Example responses

Use decision, status, sub_status, and tags together to determine the next step in your flow.

One-Time Passcode required

{
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "sub_status": "Awaiting Customer OTP",
  "tags": ["OTP Triggered"]
}

What to do:

• Prompt the user to enter a 6-digit One-Time Passcode.
• Resume the evaluation after submission.

Prefill available

{
  "decision": "ACCEPT",
  "status": "CLOSED",
  "tags": ["Prefill Successful"]
}

What to do:

• Display prefilled identity data
• Allow the user to confirm or complete missing fields.
• Continue the onboarding flow.

Prefill unavailable

{
  "decision": "ACCEPT",
  "status": "CLOSED",
  "tags": ["Prefill Unsuccessful"]
}

What to do:

• Display a blank onboarding form.
• Collect identity data manually.

Additional PII required

{
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "sub_status": "More information needed",
  "tags": ["Additional PII Requested"]
}

What to do:

• Collect full identity data (name, address, etc.).
• Resume the evaluation.

High risk reject

{
  "decision": "REJECT",
  "status": "CLOSED",
  "tags": ["Phone - High Risk"]
}

What to do:

• Stop the flow or route to fallback handling.

Routing logic

Handle One-Time Passcode

If the response indicates One-Time Passcode is required:

• decision = REVIEW
• status = ON_HOLD
• sub_status = Awaiting Customer OTP
• tags = ["OTP Triggered"]

What to do

1. Prompt the user to enter a 6-digit One-Time Passcode.
2. Submit the One-Time Passcode using PATCH /api/evaluation/{eval_id}.
3. Continue the evaluation.

See Handle Additional Verification for the full One-Time Passcode flow.

Handle additional identity data

If additional identity data is required:

• sub_status = More information needed
• tags = ["Additional PII Requested"]

What to do

1. Display your full onboarding form.
2. Collect required identity fields (name, address, etc.).
3. Submit the data using PATCH /api/evaluation/{eval_id}.
4. Continue the evaluation.

Handle Prefill

Prefill data may not always be approved for display, even when available. In these cases, display a blank onboarding form and collect identity data manually.

Prefill successful

• Display prefilled identity data.
• Allow the user to confirm or edit fields.
• Continue onboarding.

Prefill unavailable

• Display a blank onboarding form.
• Collect identity data manually.

Handle Document Verification (DocV)

If additional verification is required, RiskOS™ may trigger Document Verification.

What to do

1. Detect the DocV trigger.
2. Direct the user to complete document capture.
3. Wait for completion.
4. Continue the evaluation or wait for final decision.

See Handle Additional Verification for the full DocV flow.

Final decision

Some evaluations complete immediately, while others (such as DocV flows) complete asynchronously.

Error handling

If the API returns an HTTP error (4xx or 5xx), your application should handle it before processing any evaluation logic.

For the full error schema and all error codes, see the Errors Reference.

Data handling

What to persist

Store these fields:

• id
• eval_id
• decision
• status
• sub_status
• workflow (optional)

Implementation flow

1. Start an evaluation.
2. Store the eval_id.
3. Interpret the response.
4. Route the user:
   • One-Time Passcode
   • Additional PII
   • Prefill
   • Reject
5. Continue using PATCH /api/evaluation.
6. Handle final decision.

Summary

• The API response determines the next step.
• Your application controls the user experience.
• Routing is based on decision, sub_status, and tags.
• Continue the evaluation until a final decision is reached.