Handle Advanced Prefill Decisions & Step-Up Flows

Overview

When the Advanced Prefill workflow completes, it returns one of three outcomes: ACCEPT, REJECT, or ON_HOLD. This page covers how your integration detects, handles, and completes each flow — including OTP step-ups and the transition to Consumer Onboarding.

Decision routing

Every Advanced Prefill evaluation produces a decision that determines the next action in your integration.

📘

Note:

Advanced Prefill decisions are data disclosure decisions, not final onboarding decisions. Do not use them to approve or reject applicants. The Consumer Onboarding workflow makes the final KYC and fraud determination.

Common outcomes

Step-up path: OTP verification

Advanced Prefill uses a single step-up path. When Silent Network Authentication (SNA) cannot verify phone possession, the workflow pauses and requests a one-time passcode.

flowchart TD
    A[Evaluation submitted] --> B{Device and phone checks}
    B -->|High risk or deny match| C[REJECT]
    B -->|Pass| D{SNA verification}
    D -->|Success| E[Run Prefill]
    D -->|Fail or unavailable| F[ON_HOLD — collect OTP]
    F --> G{OTP result}
    G -->|Verified| E
    G -->|Failed or abandoned| C
    E --> H{Prefill data available?}
    H -->|Yes| I[ACCEPT — show prefilled form]
    H -->|No| C

Detect the ON_HOLD signal

Check the evaluation response for:

• status is "ON_HOLD"
• sub_status is "Awaiting Customer OTP"

Resume the evaluation

1. Prompt the user to enter the OTP delivered to their phone.
2. Send a PATCH /api/evaluation/{eval_id} request with the OTP code.
3. Handle the updated response — the evaluation returns ACCEPT or REJECT.

For the PATCH request format and field reference, see Handle OTP step-up.

OTP behavior

• The workflow resumes automatically when the OTP succeeds, fails, or expires.
• There is no API to force continuation — the evaluation remains paused until OTP resolves.
• A failed or expired OTP results in REJECT.

For OTP configuration details, see One-Time Passcode (OTP).

Consumer Onboarding handoff

After Advanced Prefill reaches a terminal state (ACCEPT or REJECT), the user reviews their information and your integration starts the Consumer Onboarding workflow.

Accepted users

When Advanced Prefill returns ACCEPT:

1. Display the prefilled identity data returned in the data_enrichments response.
2. Lock phone_number and date_of_birth as read-only — these were verified during Prefill.
3. Allow the user to review and edit other fields (name, address, email).
4. Create a new evaluation with workflow: "consumer_onboarding" when the user submits.

Rejected users

When Advanced Prefill returns REJECT:

1. Display a blank onboarding form — do not show any prefilled data.
2. Collect all required identity fields from the user manually.
3. Create a new evaluation with workflow: "consumer_onboarding" when the user submits.

What to carry forward

When creating the Consumer Onboarding evaluation:

Example Consumer Onboarding request

{
  "id": "onb-12345",
  "timestamp": "2026-04-02T12:05:00Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Jane",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1990-05-15",
      "email": "[email protected]",
      "phone_number": "+13125551234",
      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "additional_context": {
        "disclosure_purpose": "GLBA_502(e)"
      }
    }
  }
}

curl --request POST \
  --url https://riskos.sandbox.socure.com/api/evaluation \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "id": "onb-12345",
    "timestamp": "2026-04-02T12:05:00Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "given_name": "Jane",
        "family_name": "Smith",
        "national_id": "123456789",
        "date_of_birth": "1990-05-15",
        "email": "[email protected]",
        "phone_number": "+13125551234",
        "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s",
        "address": {
          "line_1": "742 Evergreen Terrace",
          "line_2": "Apt 12B",
          "locality": "Springfield",
          "major_admin_division": "IL",
          "country": "US",
          "postal_code": "62704"
        },
        "additional_context": {
          "disclosure_purpose": "GLBA_502(e)"
        }
      }
    }
  }'

For complete Consumer Onboarding request and response details, see Integrate with Consumer Onboarding.

Operational recommendations

• Design for ON_HOLD. Most sessions where SNA is unavailable fall back to OTP. Ensure your UI handles the ON_HOLD → OTP → resume flow.
• Monitor decision distribution. Track the ratio of ACCEPT, REJECT, and ON_HOLD decisions to detect shifts in coverage or risk thresholds.
• Handle OTP timeouts. If a user does not complete OTP within a reasonable window, route them to a blank form rather than leaving the evaluation indefinitely paused.
• Log routing signals. Persist decision, status, eval_id, and tags for audit and analytics.
• Do not start Consumer Onboarding early. Wait for Advanced Prefill to return ACCEPT or REJECT before initiating the Consumer Onboarding evaluation.

Common issues

Troubleshooting reference

Error codes

OTP errors

Escalation path

For production-impacting issues:

1. Reproduce the issue in Sandbox if possible.
2. Capture relevant identifiers: eval_id, full request payload, and referenceId from enrichments (if applicable).
3. Open a support ticket at [email protected] with: workflow name, input fields, expected vs. actual decision, and logs.

FAQs

Related concepts

• Consumer Onboarding
• Handle Consumer Onboarding Review & Step-Up Flows
• One-Time Passcode (OTP)
• Silent Network Authentication
• Prefill
• Evaluations
• Decisions
• Synchronous vs Asynchronous Evaluations