Integration Guide

Socure Prefill API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the Prefill enrichment. You’ll learn how to send minimal identity data, parse the response, and apply the results to streamline onboarding, back-office operations, and global enrichment workflows.

Before you start

Make sure your RiskOS™ environment is provisioned with:

Postman Collection

The following Postman collection can be used to test the Prefill enrichment with the Evaluation endpoint.

How it works

1. Send a POST request to /api/evaluation with identity data.
2. Socure runs the request through your configured RiskOS™ workflow with Prefill enrichment.
3. Receive either enriched identity data (full name, DOB, address, etc.) or an empty object.
4. Use the returned data to auto-populate forms and accelerate your workflow.

Choose your environment

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

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

Get an API key

Input signals

📘

Note :

One or a combination of the above input signals must be provided. Additional PII is required when only the last 4 digits of SSN are used as input. In International market, name, phone number + DOB is supported.

Resolution rules

• If all signals align → return best-matched identity (full name, DOB, address, etc.)
• If signals conflict, are incomplete, or have low confidence → return {} (empty object)
• If signals resemble a synthetic or fraudulent identity → return {}
• 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 → {}
• Synthetic identity detected → no trust → {}
• 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 markets and use cases.

📘

Note:

Get in touch with your account support rep to set up Prefill enrichment using other inputs.

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

This example screen shows how a mobile app might capture minimal user information, then use 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. Note that additional consent language is required from customer.

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 are required per workflow by adjusting module-level match logic in RiskOS™.

Start a new evaluation

Endpoint

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, along 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": {
      "modules": [
          "prefill"
      ],
      "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": {
      "modules": [
          "prefill"
      ],
      "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

Top-level fields

individual fields

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": "APPROVE",
  "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": {
          "aliases": [
            "S Miles",
            "Sar Miles"
          ],
          "associatedAddresses": [
            {
              "city": "Seattle",
              "firstSeenDate": "2020-01-15",
              "state": "WA",
              "streetAddress": "812 N 5th Ave Apt 12",
              "zip": "98109"
            },
            {
              "city": "Portland",
              "firstSeenDate": "2019-09-30",
              "state": "OR",
              "streetAddress": "23 Ridgeway Blvd",
              "zip": "97204"
            }
          ],
          "associatedEmails": [
            {
              "emailAddress": "[email protected]",
              "firstSeenDate": "2015-05-18",
              "lastSeenDate": "2024-01-10"
            },
            {
              "emailAddress": "[email protected]",
              "firstSeenDate": "2012-11-02",
              "lastSeenDate": ""
            }
          ],
          "associatedPhoneNumbers": [
            {
              "firstSeenDate": "2016-06-12",
              "lastSeenDate": "2024-03-14",
              "phoneNumber": "+14155553311"
            },
            {
              "firstSeenDate": "2017-02-11",
              "lastSeenDate": "2024-03-10",
              "phoneNumber": "+14155558789"
            }
          ],
          "city": "Seattle",
          "dob": "1988-07-22",
          "firstName": "Sarah",
          "mobileNumber": "+198765432100",
          "nationalId": "321654987",
          "state": "WA",
          "streetAddress": "812 N 5th Ave Apt 12",
          "surName": "Miles",
          "zip": "98109"
        },
        "referenceId": "536efe69-d36c-4393-ac1b-dde96ed27860"
      },
      "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, along 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 most recent phone number should be prefilled by default, with the option for the user to:

• Replace it with another address, or
• Select from the last three known phone number via a radio button option.
• Most recent phone number might not match the input phone number

associatedAddresses fields

Supports up to 10 addresses to provide flexibility for either manual entry or selection of known addresses. The most recent 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 option.

associatedEmails fields

Supports up to 10 email addresses to provide flexibility for either manual entry or selection of known email address. The most recent email 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 email addresses via a radio button option.
• Most recent email address might not match the input phone number

Best practices

Integration and maintenance

• Implement fallback logic for cases where Prefill fails
• Allow user override of prefilled data to maintain user control
• Log Prefill results for analytics and continuous improvement

User experience

• 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 — use Prefill data to populate forms but avoid unnecessary persistence
• 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