Integrate Prefill

Overview

This guide shows you how to:

1. Collect the minimal identity signals you have from the consumer (prefer a phone number and date of birth; name, SSN, email, and address are also supported).
2. Submit a POST /api/evaluation request from your backend with the collected signals.
3. Read the Prefill response: either enriched identity data (full name, date of birth, address, and more) or an empty object.
4. Use the returned data to auto-populate your onboarding forms and accelerate the flow.

Before you start

Postman Collection

You can use the following Postman collection to test the Prefill enrichment with the Evaluation endpoint.

How it works

Input signals

Resolution rules

• If signals align → return best-matched identity
• If signals conflict, are incomplete, or have low confidence → return {} (empty object)
• Prefill never returns partial or ambiguous matches

This ensures Prefill only returns data when inputs resolve with high confidence to one SocureID.

Matching logic flow

• Conflicting signals → no match → {}
• Match confirmed → one SocureID → identity data returned

Prefill guarantees clear outcomes only — never partial, guessed, or inconsistent responses.

Common integration patterns

The table below outlines common integration patterns for Socure Prefill across different use cases.

Example frontend input form (mapped to /api/evaluation payload)

This example screen shows how a mobile app might capture minimal user information, then use Advanced Prefill to auto-complete additional PII during onboarding using a RiskOS™ /api/evaluation request.

See the Advanced Prefill solution guide for more details on setting up OTP and incorporating device risk signals.

Each field maps to required parameters in the data.individual object:

• Email → email
• Date of Birth → date_of_birth
• Phone Number → phone_number

You can configure which fields each workflow requires by adjusting module-level match logic in RiskOS™.

Start an evaluation

Endpoint

Start with Sandbox for development and testing, then move to Production for live applications.

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

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

Authentication and headers

Include your API key in the Authorization header as a Bearer token, with standard JSON headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion   # optional – pins a specific API version

Example request

{
  "id": "prefill_test_case_01_Name_Phoneno_4SSN",
  "timestamp": "2025-11-25T20:50:21.000Z",
  "workflow": "individual_onboarding",
  "data": {
    "line_of_business": "onboarding",
    "channel": "mobile",
    "individual": {
      "given_name": "Sarah",
      "family_name": "Miles",
      "date_of_birth": "1988-07-22",
      "national_id": "4987",
      "id": "",
      "phone_number": "14155553311",
      "address": {
        "line_1": "",
        "line_2": "",
        "locality": "",
        "major_admin_division": "",
        "postal_code": "",
        "country": "US"
      }
    }
  }
}

curl --location --request POST 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
  "id": "prefill_test_case_01_Name_Phoneno_4SSN",
  "timestamp": "2025-11-25T20:51:06.000Z",
  "workflow": "individual_onboarding",
  "data": {
    "line_of_business": "onboarding",
    "channel": "mobile",
    "individual": {
      "given_name": "Sarah",
      "family_name": "Miles",
      "date_of_birth": "1988-07-22",
      "national_id": "4987",
      "id": "",
      "phone_number": "14155553311",
      "address": {
        "line_1": "",
        "line_2": "",
        "locality": "",
        "major_admin_division": "",
        "postal_code": "",
        "country": "US"
      }
    }
  }
}'

Request schema

Validation rules & accuracy guidance

Prefill returns identity data for the SocureID that the provided signals resolve to. These rules ensure RiskOS™ has a signal to match on.

Top-level fields

Path: root request object

individual fields

Path: data.individual

address

Path: data.individual.address

Example response

When you call the Evaluation API, RiskOS™ returns a JSON payload that includes the final decision, evaluation metadata, and enrichment-specific results.

{
  "id": "prefill_test_case_01_Name_Phoneno_4SSN",
  "eval_id": "6d004b47-e9c7-4f5d-b8c9-79d7039dd161",
  "workflow": "individual_onboarding",
  "workflow_id": "dc7f261e-b158-477e-9770-7e4eae066156",
  "eval_start_time": "2025-10-07T23:50:03.60187976Z",
  "eval_end_time": "2025-10-07T23:50:03.738794253Z",
  "workflow_version": "28.16.0",
  "eval_source": "API",
  "status": "CLOSED",
  "sub_status": "Accept",
  "decision": "ACCEPT",
  "decision_at": "2025-10-07T23:50:03.738648201Z",
  "tags": [],
  "review_queues": [],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Prefill",
      "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "country": "US",
        "dob": "1988-07-22",
        "firstName": "Sarah",
        "mobileNumber": "14155553311",
        "modules": [
          "prefill"
        ],
        "nationalId": "4987",
        "parentTxnId": "6d004b47-e9c7-4f5d-b8c9-79d7039dd161",
        "riskOSId": "prefill_test_case_01_Name_Phoneno_4SSN",
        "surName": "Miles",
        "workflow": "individual_onboarding"
      },
      "response": {
        "prefill": {
          "socureId": "819509ab-5ab8-475c-a084-5f209dcff940",
          "firstName": "John",
          "middleName": "",
          "surName": "Smith",
          "suffix": "",
          "nationalId": "123456789",
          "ssnFirst5": "12345",
          "dob": "1985-02-18",
          "mobileNumber": "+12015550123",
          "streetAddress": "123 Main St",
          "city": "Jersey City",
          "state": "NJ",
          "zip": "07306",
          "aliases": [],
          "associatedAddresses": [
            {
              "streetAddress": "178 Wesley St",
              "city": "Seattle",
              "firstSeenDate": "2020-01-15",
              "state": "WA",
              "streetAddress": "812 N 5th Ave Apt 12",
              "zip": "98109",
              "lastSeenDate": "2026-05-03",
              "isMatched": false,
              "isLatest": true
            },
            {
              "streetAddress": "2434 S Style Ave",
              "city": "Portland",
              "firstSeenDate": "2019-09-30",
              "state": "OR",
              "streetAddress": "23 Ridgeway Blvd",
              "zip": "97204",
              "lastSeenDate": "2023-06-16",
              "isMatched": false,
              "isLatest": false
            }
          ],
          "associatedEmails": [
            {
              "emailAddress": "[email protected]",
              "firstSeenDate": "2015-05-18",
              "lastSeenDate": "2024-01-10",
              "isMatched": false,
              "isLatest": true
            },
            {
              "emailAddress": "[email protected]",
              "firstSeenDate": "2012-11-02",
              "lastSeenDate": "",
              "isMatched": false,
              "isLatest": false
            }
          ],
          "associatedPhoneNumbers": [
            {
              "firstSeenDate": "2023-11-05",
              "lastSeenDate": "2026-01-27",
              "phoneNumber": "+12015550123",
              "isMatched": false,
              "isLatest": true
            },
            {
              "firstSeenDate": "2016-06-12",
              "lastSeenDate": "2025-03-14",
              "phoneNumber": "+14155553311",
              "isMatched": true,
              "isLatest": false
            },
            {
              "firstSeenDate": "2017-02-11",
              "lastSeenDate": "2024-03-10",
              "phoneNumber": "+14155558789",
              "isMatched": false,
              "isLatest": false
            }
          ],
          "driverLicense": "S1234-56789-01234"
        },
        "referenceId": "117f2c07-15a1-4438-b301-2c6a9c4a2123"
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "eval_status": "evaluation_completed",
  "environment_name": "Sandbox"
}

Key response fields

RiskOS™ returns a consistent set of top-level fields that describe the outcome of an evaluation, with enrichment-specific results that depend on your workflow configuration.

Where to find specific results

Decision and routing (primary control signals)

Use these fields to determine what action your application should take.

decision values are workflow-specific and may differ from the examples shown in this guide.

Evaluation lifecycle and status

These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.

Identifiers and traceability

Use these fields to correlate requests, logs, webhooks, and support cases.

Execution context

These fields provide timing and environment context for the evaluation.

Enrichment results

Enrichment outputs are returned in the data_enrichments array.

request fields

response fields

prefill fields

associatedPhoneNumbers fields

Supports up to 10 phone numbers to provide flexibility for either manual entry or selection of known phone numbers. The top ranked, first indexed phone number should be prefilled by default, with the option for the user to:

• Replace it with another phone number, or
• Select from the last three known phone numbers via a radio button option.

The top ranked, first indexed phone number in the array may be different than the most recent phone number, though they often are congruent. The most top ranked and recent phone numbers might not match the input phone number.

Note: associatedPhoneNumbers is always an array of objects, even when only one address is on file.

associatedAddresses fields

Supports up to 10 addresses to provide flexibility for either manual entry or selection of known phone numbers. The top ranked, first indexed address should be prefilled by default, with the option for the user to:

• Replace it with another address, or
• Select from the last three known addresses via a radio button.

The top ranked, first indexed address in the array may be different than the most recent address, though they often are congruent. The most top ranked and recent addresses might not match the input address.

Note: associatedAddresses is always an array of objects, even when only one address is on file.

associatedEmails fields

Supports up to 10 emails to provide flexibility for either manual entry or selection of known emails. The top ranked, first indexed email should be prefilled by default, with the option for the user to:

• Replace it with another email, or
• Select from the last three known emails via a radio button option.

The top ranked, first indexed email in the array may be different than the most recent email, though they often are congruent. The most top ranked and recent emails might not match the input email.

Note: associatedEmails is always an array of objects, even when only one address is on file.

Best practices

Integration and maintenance

• Implement fallback logic for cases where Prefill fails
• Log Prefill results for analytics and continuous improvement
• Advanced Prefill only: allow user override of prefilled data to maintain user control.

User experience (Advanced Prefill only)

• Clearly indicate prefilled fields to users (e.g., with visual cues)
• Provide easy edit functionality for all prefilled data

Security and compliance

• Store minimal PII — avoid unnecessary persistence to practice good data privacy and security
• Implement proper data retention policies for Prefill responses
• Use secure transmission (TLS 1.2+) for all API communications

Performance optimization

• Set appropriate timeouts for API calls
• Monitor API response times and optimize accordingly

Validation checklist

Validation

Test coverage

User experience

Logging and observability