Integrate with Advanced Prefill

Connect your systems to the RiskOS™ Evaluation API to submit Advanced Prefill evaluations, handle OTP step-ups, and transition to Consumer Onboarding.

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

Collect the Digital Intelligence session token on the client using the Digital Intelligence SDK.
Gather minimal identity data from the consumer: phone number and date of birth.
Submit a POST /api/evaluation request from your backend with workflow: "advanced_pre_fill".
Handle the response: display prefilled data on ACCEPT, collect OTP on ON_HOLD, or show a blank form on REJECT.
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

A configured Advanced Prefill workflow.

Integration with the Digital Intelligence SDK to collect the di\_session\_token.

A two-field identity form to collect the consumer's phone number and date of birth.

An OTP submission form to collect a one-time passcode when the evaluation enters ON\_HOLD.

A primary onboarding form to display prefilled or manually entered identity data.

A RiskOS™ API key from Developer Workbench > API Keys in the Dashboard.

Carrier approval if using SIM Swap or Silent Network Authentication with supported U.S. carriers (AT\&T, Verizon, T-Mobile).

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

Field	Type	Required	Description	Example
`id`	String	Required	Customer-defined unique identifier for the request. This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run.	`"a86580cc-1733-4188-86b5-717166e1db8c"`
`timestamp`	String `<Date-Time>`	Required	RFC 3339 timestamp indicating when the evaluation request was initiated by your system.	`"2026-04-02T12:00:00Z"`
`workflow`	String	Required	Your environment-specific workflow identifier. Find this in the RiskOS™ Dashboard > Developer Workbench > Integration Checklist. Use `"advanced_pre_fill"` for Advanced Prefill.	`"advanced_pre_fill"`
`data`	Object	Required	Main payload containing consumer information and device data.	`{ "individual": { … } }`

Individual fields

Path: data.individual

Field	Type	Required	Description	Example
`phone_number`	String	Required	Consumer's phone number in E.164 format. Hyphens and spaces are tolerated.	`"+16673681976"`
`date_of_birth`	String	Required	Consumer's date of birth in ISO 8601 format (`YYYY-MM-DD`).	`"1992-03-11"`
`di_session_token`	String (UUID)	Required	Token from the Digital Intelligence SDK that links the device session. Must be generated client-side before submitting the evaluation.	`"YOUR_DI_SESSION_TOKEN"`
`email`	String	Optional	Consumer's email address. May improve deny list screening.	`"[email protected]"`
`given_name`	String	Optional	Consumer's first name. May improve Prefill match accuracy.	`"Franky"`
`family_name`	String	Optional	Consumer's last name. May improve Prefill match accuracy.	`"Valley"`
`national_id`	String	Optional	National identification number (SSN, ITIN). Partial (last four digits) accepted. Hyphens are optional.	`"555667772"`
`id`	String	Optional	Customer-defined identifier that maps to `userId` in enrichments or internal systems.	`"username"`

Address fields

Path: data.individual.address

Field	Type	Required	Description	Example
`line_1`	String	Optional	The first line of the consumer's address.	`"742 Evergreen Terrace"`
`line_2`	String	Optional	An optional second line for the address, such as apartment number, suite, or building landmarks.	`"Apt 2B"`
`locality`	String	Optional	City, town, or village name where the consumer resides.	`"Springfield"`
`major_admin_division`	String	Optional	The state, province, or region where the consumer resides.	`"IL"`
`country`	String	Optional	The country where the consumer resides, specified in ISO 3166-1 alpha-2 country code format.	`"US"`
`postal_code`	String	Optional	The consumer's ZIP code, postal code, or equivalent regional identifier for mail delivery.	`"62704"`

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

Handling responses

Decision routing

Decision	Status	Action
`ACCEPT`	`CLOSED`	Display prefilled identity data and continue onboarding
`REJECT`	`CLOSED`	Present a blank onboarding form for manual entry
—	`ON_HOLD`	Collect OTP and resume the evaluation with `PATCH /api/evaluation/{eval_id}`

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

On ACCEPT, the Prefill enrichment discloses verified identity data in data_enrichments[].response.prefill. On ON_HOLD and REJECT, no prefill data is disclosed — the enrichment still runs and returns a referenceId, but the prefill object is omitted because the disclosure gate has not passed.

{
  "id": "advanced-prefill-03f1de",
  "workflow": "advanced_pre_fill",
  "eval_id": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
  "eval_status": "evaluation_completed",
  "decision": "ACCEPT",
  "status": "CLOSED",
  "eval_start_time": "2026-04-02T12:00:00.196Z",
  "eval_end_time": "2026-04-02T12:00:02.007Z",
  "tags": ["none"],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Prefill",
      "enrichment_provider": "Socure",
      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
      "status_code": 200,
      "response": {
        "customerProfile": {
          "userId": "555adc5d-5f55-555b-a5ef-5555a4555ce5"
        },
        "prefill": {
          "socureId": "afe5bd55-a555-5555-55bb-55f55a55ed5c",
          "firstName": "Bart",
          "middleName": "A",
          "surName": "Lambert",
          "suffix": "Jr",
          "aliases": ["el barto"],
          "dob": "2001-01-10",
          "ssnFirst5": "56790",
          "nationalId": "567905555",
          "mobileNumber": "+15556678910",
          "associatedPhoneNumbers": [
            {
              "phoneNumber": "+15556678910",
              "isMatched": true,
              "isLatest": true,
              "firstSeenDate": "2020-07-01",
              "lastSeenDate": "2025-11-01"
            }
          ],
          "associatedEmails": [
            {
              "emailAddress": "[email protected]",
              "isMatched": true,
              "isLatest": false,
              "firstSeenDate": "2010-01-28",
              "lastSeenDate": "2026-03-22"
            }
          ],
          "associatedAddresses": [
            {
              "streetAddress": "123 4th Ave",
              "city": "Springfield",
              "county": "Lane",
              "state": "OR",
              "zip": "55668",
              "isMatched": false,
              "firstSeenDate": "",
              "lastSeenDate": ""
            }
          ]
        },
        "referenceId": "555e5555-55e5-5a55-5555-f5dcfddd5555"
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ]
}

{
  "id": "advanced-prefill-03f1de",
  "workflow": "advanced_pre_fill",
  "eval_id": "500c6b88-9f5c-4d62-9422-163a59a343fe",
  "eval_status": "evaluation_in_progress",
  "status": "ON_HOLD",
  "sub_status": "Awaiting Customer OTP",
  "eval_start_time": "2026-04-02T12:00:00.196Z",
  "eval_end_time": "2026-04-02T12:00:01.512Z",
  "tags": ["none"],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Prefill",
      "enrichment_provider": "Socure",
      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
      "status_code": 200,
      "response": {
        "referenceId": "b28f5e77-2c41-4a90-8d3e-6f1a9c7b0e42"
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ]
}

{
  "id": "advanced-prefill-03f1de",
  "workflow": "advanced_pre_fill",
  "eval_id": "8a12f3e4-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
  "eval_status": "evaluation_completed",
  "decision": "REJECT",
  "status": "CLOSED",
  "eval_start_time": "2026-04-02T12:00:00.196Z",
  "eval_end_time": "2026-04-02T12:00:01.884Z",
  "tags": ["none"],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Prefill",
      "enrichment_provider": "Socure",
      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
      "status_code": 200,
      "response": {
        "referenceId": "c39a6f88-3d52-4b01-9e4f-7a2b8d6c1f53"
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ]
}

Key response fields

Area	Fields	Purpose
Decision and routing	`decision`, `status`	Primary signals — use `decision` for logic, `status = ON_HOLD` for OTP
Evaluation lifecycle	`eval_status`, `eval_start_time`, `eval_end_time`	Track whether the evaluation completed (`evaluation_completed`) or is still in progress (`evaluation_in_progress`)
Traceability	`id`, `eval_id`	Persist for OTP resume (`PATCH`) and cross-workflow correlation
Prefill data	`data_enrichments[].response.prefill`	Verified identity data to display on `ACCEPT` — includes name fields, `dob`, `ssnFirst5`, `nationalId`, `mobileNumber`, `aliases`, and the `associatedPhoneNumbers`, `associatedEmails`, and `associatedAddresses` arrays
Prefill traceability	`data_enrichments[].response.customerProfile.userId`, `data_enrichments[].response.referenceId`	Identifiers Socure returns with the Prefill result
Diagnostic only	`sub_status`, `tags`, `notes`	Use for debugging, not primary decisioning

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

Field	Required	Description
`id`	Yes	Same customer-defined request identifier from the initial request
`timestamp`	Yes	RFC 3339 timestamp
`workflow`	Yes	`"advanced_pre_fill"`
`data.individual.otp.code`	Yes	OTP entered by the user

After OTP

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

Condition	Action
`decision = ACCEPT`	Show prefilled identity data and continue onboarding
`decision = REJECT`	Show a blank onboarding form or fallback flow

For additional OTP details, see the OTP Integration Guide.

Integration testing

Low-risk inputs return ACCEPT with prefilled data

High-risk or deny-listed inputs return REJECT

SNA failure triggers ON\_HOLD and OTP flow completes correctly

Phone number is validated in E.164 format before submission

di\_session\_token is collected from an active Digital Intelligence session

Error responses are captured, logged, and handled

id and eval\_id are persisted for traceability

Consumer Onboarding starts as a new evaluation after Advanced Prefill completes

Before going live

Production API key is provisioned and securely stored

Production workflow is published and active

Carrier approval is obtained for SIM Swap and SNA (if applicable)

Monitoring is configured for decision distribution and latency

Sensitive data (national ID, date of birth, API keys) is redacted from logs

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

FAQs

What format should the di_session_token be in?

The di_session_token is a JWT string generated by the Digital Intelligence SDK on the client side. Pass it as-is to the Evaluation API. See the Digital Intelligence SDK documentation for integration details.

Can I use different PII inputs?

The solution accepts various forms of PII. Only phone_number, date_of_birth, and di_session_token are required. Including additional fields such as email, given_name, or address can improve match accuracy.

Can I submit the evaluation without the Digital Intelligence SDK?

You can submit requests without a di_session_token, but the Digital Intelligence enrichment does not produce device risk signals. This reduces the accuracy of the data disclosure gate. Device session collection is recommended.

What should I do if the API returns an error?

Log the error response including the id you submitted and any error details returned. Use exponential backoff with jitter for transient errors (5xx). For 4xx errors, validate your request against the schema requirements above.

Related concepts

Updated 10 days ago

What’s Next

Handle Advanced Prefill Decisions & Step-Up Flows

Did this page help you?