## Before you start

Make sure your RiskOS™ environment is provisioned with:

- [A workflow configured](https://help.socure.com/riskos/docs/prefill-riskos-setup#/) for the **Prefill** enrichment.
- [Regional support coverage](https://help.socure.com/riskos/docs/prefill#/) 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.

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

- **No real customer data**
- **Free testing environment**
- **Unlimited API calls**

```undefined
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**](https://riskos.sandbox.socure.com/developers/api-keys).
2. Copy your API key securely.

1. In the Production RiskOS™ Dashboard, go to [**Developer Workbench > API Keys**](https://riskos.sandbox.socure.com/developers/api-keys).
2. Copy your API key securely.

### Input signals

| **Field** | **Type** | **Description** | **Example** |
| --- | --- | --- | --- |
| `phone_number` | String | Consumer's phone number in E.164 format. The API expects the standard E.164 format but tolerates hyphens and spaces for user convenience. | `"+1-415-555-1234"` |
| `email` | String | Consumer's email address. | `"user@example.com"` |
| `date_of_birth` | String | Consumer's date of birth in ISO 8601 format (`YYYY-MM-DD`). | `"1990-05-20"` |
| `address` | Object | Consumer's physical address (full or partial). | `{"line_1": "123 Main St", "locality": "SF", "postal_code": "94105"}` |
| `national_id` | String | Consumer's government-issued ID (last 4 SSN for U.S., full ID for others). | `"4987"` |

> 📘
>
> **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.

| **Example** | **Required Inputs** | **Response Returned** | **Markets supported** |
| --- | --- | --- | --- |
| Example 1 | Name + National ID + Phone Number | DOB, Address, Email | US |
| Example 2 | Name + Last 4 of SSN + Phone | DOB, Address, Email | US |
| Example 3 | Email + Phone number + Last 4 of SSN | Name, Address | US |
| Example 4 | Phone number + DOB | Name, Address, Email, National ID (in US) | US |

> 📘
>
> **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

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

```http
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:

```http
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

```json
{
  "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
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

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | String | Required | Required, customer-defined unique identifier for the request.<br>This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run and can impact processing behavior, results, and downstream workflows. | `"prefill_test_case_01_Name_Phoneno_4SSN"` |
| `timestamp` | String | Required | RFC 3339 timestamp when the request was created. | `"2025-10-07T23:50:03Z"` |
| `workflow` | String | Required | RiskOS™ workflow name configured in your environment. <br>**Note:** The workflow name must be unique within your RiskOS™ environment. It is not scoped by use case and must identify a single active workflow for each Evaluation API request. | `"individual_onboarding"` |
| `data` | Object | Required | Main payload containing business and individual information |  |
| →`modules` | Array | Required | Must include `"prefill"`. | `[
"prefill"` |
| →`line_of_business` | String | Optional | Business context (for example, `"onboarding"`). | `"onboarding"` |
| →`channel` | String | Optional | Channel context (for example, `"mobile"`). | `"mobile"` |
| →`individual` | Object | Required | Primary identity object. | See `individual` schema below.

#### `individual` fields

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `given_name` | String | Optional | First name of the individual. | `"Sarah"` |
| `family_name` | String | Optional | Last name of the individual. | `"Miles"` |
| `national_id` | String | Optional | Government-issued ID (last 4 SSN for U.S., full ID for others). | `"4987"` |
| `date_of_birth` | String | Optional | Date of birth in `YYYY-MM-DD` format. | `"1988-07-22"` |
| `address` | Object | Optional | Residential address of the individual. | See `address` schema below. |
| `phone_number` | String | Optional | Phone number in E.164 format. | `"14155553311"` |
| `email` | String | Optional | Individual’s email address. | `"sarah.miles@example.com"` |

#### `address`

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `line_1` | String | Optional | Street address line 1. | `"812 N 5th Ave"` |
| `line_2` | String | Optional | Street address line 2. | `"Apt 12"` |
| `locality` | String | Optional | City. | `"Seattle"` |
| `major_admin_division` | String | Optional | State, province, or region. | `"WA"` |
| `postal_code` | String | Optional | Postal or ZIP code. | `"98109"` |
| `country` | String | Required | Country code in ISO 3166-1 alpha-2 format. | `"US"` |

## Example response

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

```json
{
  "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)

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `decision` | String enum | Final evaluation result.<br>Possible values:<br>• `ACCEPT`<br>• `REVIEW`<br>• `REJECT`<br>**Note**: The fields returned can be customized to fit your integration or business needs. | `"ACCEPT"` |
| `decision_at` | String `<Date-Time>` | RFC 3339 timestamp when the decision was finalized. | `"2025-10-07T23:50:03.738648201Z"` |
| `score` | Number | If configured for a workflow, provides an aggregate score of all steps. This can be used for risk banding, additional routing, or analytics alongside the primary `decision` value. | `0.91` |
| `tags` | Array of strings | Array of labels applied during the workflow to highlight routing choices, notable signals, or rule outcomes. Useful for reporting, segmentation, or UI highlighting in the RiskOS™ Dashboard. | `[]` |
| `review_queues` | Array of strings | Lists any manual review queues the evaluation was sent to. Empty when the case is fully auto-resolved without human review. | `[]` |
| `notes` | String | Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context. | `"Identity verified with high confidence"` |

### Evaluation lifecycle and status

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `eval_status` | String enum | Indicates the current state of an evaluation in RiskOS™.<br>Possible values:<br>• `evaluation_completed`<br>• `evaluation_paused`<br>• `evaluation_in_progress` | `"evaluation_completed"` |
| `status` | String enum | Indicates the current state of an evaluation or case.<br>Possible values:<br>• `OPEN`<br>• `CLOSED` | `"CLOSED"` |
| `sub_status` | String | Provides additional detail about the evaluation status.<br>Example values:<br>• `Under Review`<br>• `Pending Verification`<br>• `Accept`<br>• `Reject` | `"Accept"` |