## 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](https://help.socure.com/riskos/docs/configure-advanced-prefill-workflow). For decision routing, step-up details, and troubleshooting, see [Handle Decisions & Step-Up Flows](https://help.socure.com/riskos/docs/handle-advanced-prefill-decisions). ## System architecture ``` RiskOS™Your BackendDigital Intelligence SDKClient AppEnd UserRiskOS™Your BackendDigital Intelligence SDKClient AppEnd Useralt[ACCEPT][REJECT][ON_HOLD (OTP required)]Initialize SDKdi_session_tokenEnter phone + DOBSubmit phone + DOB + di_session_tokenPOST /api/evaluation (Advanced Prefill)Prefilled identity dataShow prefilled formNo data disclosedShow blank formstatus = ON_HOLDPrompt OTP entryEnter OTPSubmit OTPPATCH /api/evaluation/{eval_id}Final prefill decisionShow prefilled or blank formReview and submit formSubmit full identity dataPOST /api/evaluation (Consumer Onboarding)Final onboarding decision ``` ## Integration flow 1. **Collect the Digital Intelligence session token** on the client using the [Digital Intelligence SDK](https://help.socure.com/riskos/docs/digital-intelligence-sdks). 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](https://help.socure.com/riskos/docs/handle-advanced-prefill-decisions#consumer-onboarding-handoff). ## Required components A [configured Advanced Prefill workflow](https://help.socure.com/riskos/docs/configure-advanced-prefill-workflow). Integration with the [Digital Intelligence SDK](https://help.socure.com/riskos/docs/digital-intelligence-sdks) 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](https://riskos.sandbox.socure.com/developers/key-management) in the Dashboard. **Carrier approval** if using SIM Swap or Silent Network Authentication with supported U.S. carriers (AT\&T, Verizon, T-Mobile). ## Endpoint HTTP ```http POST https://riskos.sandbox.socure.com/api/evaluation ``` HTTP ```http POST https://riskos.socure.com/api/evaluation ``` Include your API key in the `Authorization` header: HTTP ```http Authorization: Bearer YOUR_API_KEY Content-Type: application/json Accept: application/json ``` ## Example request JSONcURL ```json { "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 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 ### 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 `` | 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. | `"frankeyV@test.com"` | | `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"` | ## 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. ACCEPT ```json { "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": "myemail@gmail.com", "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 } ] } ``` ```json { "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 } ] } ``` ```json { "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](https://help.socure.com/riskos/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: HTTP ```http PATCH /api/evaluation/{eval_id} ``` JSONcURL ```json { "id": "advanced-prefill-03f1de", "timestamp": "2026-04-02T12:01:00Z", "workflow": "advanced_pre_fill", "data": { "individual": { "otp": { "code": "123456" } } } } ``` ```curl 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](https://help.socure.com/riskos/docs/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](https://help.socure.com/riskos/docs/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](https://help.socure.com/riskos/docs/digital-intelligence-sdks) 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.