Integrate Prefill

Before you start

Make sure your RiskOS™ environment is provisioned with:

• A workflow configured for the Prefill enrichment.
• Regional support coverage for the Prefills enrichment.

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

• No real customer data
• Free testing environment
• Unlimited API calls

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

• Real customer data
• API usage charges apply
• Connects to live data services

Get an API key

1. In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.

2. Copy your API key securely.

3. In the Production RiskOS™ Dashboard, go to Developer Workbench > API Keys.

4. Copy your API key securely.

Input signals

📘

Note :

One or a combination of the above input signals must be provided. Phone_number + DOB is the most preferred for precision of Prefill.

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.

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

SandboxProduction

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": "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": {
        "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": "sarah.miles@example.com",
          "firstSeenDate": "2015-05-18",
          "lastSeenDate": "2024-01-10"
        }, {
          "emailAddress": "s.miles88@example.com",
          "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",
        "ssnFirst5": "32165",
        "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.

Decision and routing (primary control signals)

Evaluation lifecycle and status