Process Prefill Verification Results

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 decision was made and what action is required next

For the full response schema, see the Evaluation API Reference.

Evaluation flow (how decisions are made)

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 Verify, fraud, synthetic identity, and watchlist 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

Outcome handling

REVIEW — One-Time Passcode required

📘

Note:

See Handle Additional Verification for full implementation details for OTP, identity data collection, and DocV flows.

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

{
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "sub_status": "Awaiting Customer OTP",
  "tags": [
    "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.

{
  "decision": "ACCEPT",
  "status": "CLOSED",
  "sub_status": "Accept",
  "tags": [
    "OTP Triggered",
    "OTP Approved",
    "Prefill Successful",
    "Approved to Display the Prefill Data"
  ]
}

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

Example: phone risk reject

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

Example: Verify reject

{
  "decision": "REJECT",
  "status": "CLOSED",
  "sub_status": "Reject",
  "tags": [
    "OTP Triggered",
    "OTP Approved",
    "Prefill Unsuccessful",
    "Additional PII Requested",
    "SSN Does Not Match - Reject",
    "Verify Reject"
  ]
}

Example: watchlist reject

{
  "decision": "REJECT",
  "status": "CLOSED",
  "sub_status": "Reject",
  "tags": [
    "Phone - High Risk",
    "OTP Triggered",
    "OTP Approved",
    "Prefill Unsuccessful",
    "Additional PII Requested",
    "Watchlist Review"
  ]
}

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.

Route the user

Use decision as the primary routing field, then use status, sub_status, and tags to refine the user experience.

if (data.decision === "REVIEW" && data.status === "ON_HOLD") {
  if (data.sub_status === "Awaiting Customer OTP" && data.tags?.includes("OTP Triggered")) {
    router.push("/enter-otp");
  }

  if (
    data.sub_status === "More information needed" &&
    data.tags?.includes("Additional PII Requested")
  ) {
    if (data.tags?.includes("Prefill Successful")) {
      router.push("/prefill-review");
    } else {
      router.push("/complete-identity");
    }
  }
}

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.

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.