Integrate with Advanced Prefill

Overview

This guide covers the system integration for Advanced Prefill: connecting your frontend and backend to the Evaluation API, submitting requests, handling OTP step-ups, and transitioning to Consumer Onboarding.

For workflow configuration and enrichment setup, see Configure the Workflow. For decision routing, step-up details, and troubleshooting, see Handle Decisions & Step-Up Flows.

System architecture

sequenceDiagram
    participant EU as End User
    participant Client as Client App
    participant DI as Digital Intelligence SDK
    participant Backend as Your Backend
    participant RiskOS as RiskOS™

    Client->>DI: Initialize SDK
    DI-->>Client: di_session_token
    EU->>Client: Enter phone + DOB
    Client->>Backend: Submit phone + DOB + di_session_token
    Backend->>RiskOS: POST /api/evaluation (Advanced Prefill)

    alt ACCEPT
        RiskOS-->>Backend: Prefilled identity data
        Backend-->>Client: Show prefilled form
    else REJECT
        RiskOS-->>Backend: No data disclosed
        Backend-->>Client: Show blank form
    else ON_HOLD (OTP required)
        RiskOS-->>Backend: status = ON_HOLD
        Backend-->>Client: Prompt OTP entry
        EU->>Client: Enter OTP
        Client->>Backend: Submit OTP
        Backend->>RiskOS: PATCH /api/evaluation/{eval_id}
        RiskOS-->>Backend: Final prefill decision
        Backend-->>Client: Show prefilled or blank form
    end

    EU->>Client: Review and submit form
    Client->>Backend: Submit full identity data
    Backend->>RiskOS: POST /api/evaluation (Consumer Onboarding)
    RiskOS-->>Backend: Final onboarding decision

Integration flow

1. Collect the Digital Intelligence session token on the client using the Digital Intelligence SDK.
2. Gather minimal identity data from the consumer: phone number and date of birth.
3. Submit a POST /api/evaluation request from your backend with workflow: "advanced_pre_fill".
4. Handle the response: display prefilled data on ACCEPT, collect OTP on ON_HOLD, or show a blank form on REJECT.
5. Start Consumer Onboarding — After the user reviews and submits their information, create a new evaluation with workflow: "consumer_onboarding". See Handle Decisions & Step-Up Flows.

Required components

Endpoint

POST https://riskos.sandbox.socure.com/api/evaluation

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Example request

{
  "id": "a86580cc-1733-4188-86b5-717166e1db8c",
  "timestamp": "2026-04-02T12:00:00Z",
  "workflow": "advanced_pre_fill",
  "data": {
    "individual": {
      "phone_number": "+16673681976",
      "date_of_birth": "1992-03-11",
      "di_session_token": "YOUR_DI_SESSION_TOKEN"
    }
  }
}

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": "a86580cc-1733-4188-86b5-717166e1db8c",
    "timestamp": "2026-04-02T12:00:00Z",
    "workflow": "advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+16673681976",
        "date_of_birth": "1992-03-11",
        "di_session_token": "YOUR_DI_SESSION_TOKEN"
      }
    }
  }'

Request fields

📘

Note:

For the complete field schema, see the Evaluation API Reference.

Top-level fields

Path: root request object

Individual fields

Path: data.individual

Address fields

Path: data.individual.address

👍

Tip:

Including optional fields such as email, given_name, or address can improve Prefill match accuracy.

Handling responses

Decision routing

Use the decision field as your primary routing signal. Use status = ON_HOLD to detect OTP step-ups. Do not use sub_status for primary decisioning.

Example responses

{
  "id": "advanced-prefill-03f1de",
  "workflow": "advanced_pre_fill",
  "eval_id": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
  "decision": "ACCEPT",
  "status": "CLOSED",
  "data_enrichments": [
    {
      "enrichment_name": "Socure Prefill",
      "response": {
        "prefill": {
          "firstName": "Alex",
          "surName": "Martin"
        }
      }
    }
  ]
}

{
  "workflow": "advanced_pre_fill",
  "eval_id": "500c6b88-9f5c-4d62-9422-163a59a343fe",
  "status": "ON_HOLD",
  "sub_status": "Awaiting Customer OTP"
}

{
  "workflow": "advanced_pre_fill",
  "eval_id": "8a12f3e4-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
  "decision": "REJECT",
  "status": "CLOSED"
}

Key response fields

For complete response field definitions, see the Evaluation API Reference.

Handle OTP step-up

When the response returns status: ON_HOLD, collect a one-time passcode from the user and resume the same evaluation.

Resume request

Send a PATCH request using the eval_id from the initial response:

PATCH /api/evaluation/{eval_id}

{
  "id": "advanced-prefill-03f1de",
  "timestamp": "2026-04-02T12:01:00Z",
  "workflow": "advanced_pre_fill",
  "data": {
    "individual": {
      "otp": {
        "code": "123456"
      }
    }
  }
}

curl --request PATCH \
  --url https://riskos.sandbox.socure.com/api/evaluation/{eval_id} \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "id": "advanced-prefill-03f1de",
    "timestamp": "2026-04-02T12:01:00Z",
    "workflow": "advanced_pre_fill",
    "data": {
      "individual": {
        "otp": {
          "code": "123456"
        }
      }
    }
  }'

Required fields

After OTP

After the PATCH request, RiskOS™ resumes the evaluation and returns an updated response:

For additional OTP details, see the OTP Integration Guide.

Integration testing

Before going live

For a comprehensive go-live process, see the Go-Live Checklist.

FAQs

Related concepts

• Handle Decisions & Step-Up Flows
• Consumer Onboarding
• Evaluation API Reference
• Digital Intelligence SDKs
• OTP Integration Guide
• Evaluations
• Decisions
• Synchronous vs Asynchronous Evaluations