---
title: US Identity Fill Premium
slug: us-apis/us-identity-fill-premium
description: Learn how to use the Identity Verify API to verify consumer identities and confirm phone number ownership. This comprehensive document covers the parameters required for collecting and querying data, including consent status, phone number formatting, name
createdAt: 2023-01-31T12:44:28.000Z
---

## Introduction

The **US Identity fill premium API&#x20;**&#x72;etrieves verified individual identity details using minimal user input. The API is designed to prefill onboarding forms with accurate customer data while minimizing user friction. The API accepts a simple input payload and returns a standardized identity response containing name, address, date of birth, and SSN (wherever available) to maximize the user coverage across databases&#x20;

### Key Benefits

- Faster form completion with minimal input.
- Improved conversion rates by reducing drop-offs during onboarding.
- Accurate data prefill, minimizing typos or misinformation.
- Reduced fraud risk by verifying identity from trusted sources.

### Common Use Cases

1. Digital Onboarding for Financial Services
   - Prefill bank account opening, credit card, or loan applications using just phone number and SSN
2. E-commerce & Checkout Optimization
   - Autofill shipping and billing information to reduce cart abandonment.
3. Insurance Application Prefill
   - Populate insured's personal data (name, DOB, address) to reduce form fatigue and improve submission rates.
4. Telecom or Utility Service Enrollment
   - Streamline sign-up for phone, internet, or energy services using limited user input.
5. Identity Verification for Gig or Rental Platforms
   - Prefill background check and ID verification forms for faster user onboarding.
6. Healthcare Patient Registration
   - Populate intake forms securely with verified identity data using SSN & phone, reducing administrative overhead.

### Sample cURL

::::Tabs
:::Tab{title="Production"}
```curl
curl --location 'https://api.signzy.us/api/v3/us/identity-fill-premium' \
--header 'Content-Type: application/json' \
--header 'Authorization: XXXXX' \
--data-raw '{
    "ssn": "",
    "addressLine1": "",
    "addressLine2": "",
    "city": "",
    "state": "",
    "zip": "",
    "firstName": "",
    "middleName": "",
    "lastName": "",
    "driverLicense": "",
    "email": "",
    "phoneNumber": "",
    "consentStatus": "optedIn",
    "consentOptinType": "Whitelist",
    "consentOptinMethod": "TCO",
    "consentOptinDuration": "ONE",
    "consentOptinId": "",
    "consentOptinTimestamp": "2025-11-29T16:00:00.016Z",
    "consentOptinUrl":"" 
}'
```
:::

:::Tab{title="Pre-production"}
```curl
curl --location 'https://api-preproduction.signzy.us/api/v3/us/identity-fill-premium' \
--header 'Content-Type: application/json' \
--header 'Authorization: XXXXX' \
--data-raw '{
    "ssn": "",
    "ssn4": "",
    "addressLine1": "",
    "addressLine2": "",
    "city": "",
    "state": "",
    "zip": "",
    "firstName": "",
    "middleName": "",
    "lastName": "",
    "driverLicense": "",
    "email": "",
    "phoneNumber": "",
    "consentStatus": "optedIn",
    "consentOptinType": "Whitelist",
    "consentOptinMethod": "TCO",
    "consentOptinDuration": "ONE",
    "consentOptinId": "",
    "consentOptinTimestamp": "2025-11-29T16:00:00.016Z",
    "consentOptinUrl":"" 
}'
```
:::
::::

:::hint{type="info"}
**Minimum Input Requirements :-&#x20;**

The request must contain **phoneNumber** (mandatory). Exactly one of the following identifiers must be provided: **dob&#x20;**(YYYY-MM-DD) or ssn (9 digits). Both **dob** and **ssn** must not be provided together.
:::

### Request Body Parameters



| Parameter             | Data Type | Required   | Description                                                                    |
| --------------------- | --------- | ---------- | ------------------------------------------------------------------------------ |
| ssn                   | String    | Optional\* | Must be exactly 9 digits (numeric only). Example: 123456789                    |
| dob                   | String    | Optional\* | Must be in YYYY-MM-DD format. Valid date, not future, not older than 200 years |
| addressLine1          | String    | Optional   | House number, street name, or PO Box                                           |
| addressLine2          | String    | Optional   | Apartment, Unit, Suite (additional info)                                       |
| city                  | String    | Optional   | City name                                                                      |
| state                 | String    | Optional   | Must be 2 uppercase letters (e.g., CA)                                         |
| zip                   | String    | Optional   | Must be exactly 5 digits                                                       |
| firstName             | String    | Optional   | Given name                                                                     |
| middleName            | String    | Optional   | Middle name or initial                                                         |
| lastName              | String    | Optional   | Family name                                                                    |
| driverLicense         | String    | Optional   | Driver’s license number (state-specific format allowed)                        |
| email                 | String    | Optional   | Must be a valid email format                                                   |
| phoneNumber           | String    | Required   | Must start with +1 or 1 followed by exactly 10 digits                          |
| consentStatus         | String    | Required   | One of: optedIn, optedOut, notCollected, Y, N                                  |
| consentOptinType      | String    | Required   | Must be 'Whitelist'                                                            |
| consentOptinMethod    | String    | Required   | One of: TCO, MA, TCP, IVR, SMS, OTHER                                          |
| consentOptinDuration  | String    | Required   | Must be ONE or ONG                                                             |
| consentOptinId        | String    | Required   | Unique opt-in identifier                                                       |
| consentOptinTimestamp | String    | Required   | ISO format (YYYY-MM-DDTHH\:mm\:ss.sssZ), not future                            |
| consentOptinUrl       | String    | Optional   | URL string                                                                     |

### Sample Response&#x20;

```json
{
  "result": {
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "description": "Success",
    "response": {
      "phoneNumber": "(415) 555-2671",
      "countryCode": "US",
      "individual": {
        "firstName": "Joe",
        "middleName": "A",
        "lastName": "Doe",
        "addresses": [
          {
            "address": "1600 Amphitheatre Parkway, Mountain View",
            "extendedAddress": "Apt 2B",
            "city": "Springfield",
            "region": "IL",
            "postalCode": "62704"
          }
        ],
        "ssn": "XXX-XX-1234",
        "dob": "1990-01-01"
      }
    }
  },
  "reason": "Request Successful",
  "code": "S001"
}
```

### Response Body Parameters

| Parameter                                               | Data Type | Description                                      |
| ------------------------------------------------------- | --------- | ------------------------------------------------ |
| result.requestId                                        | string    | Unique identifier for the request                |
| result.description                                      | string    | Status description of the API response           |
| result.response.phoneNumber                             | string    | Phone number associated with the individual      |
| result.response.countryCode                             | string    | Country code of the phone number                 |
| result.response.individual.firstName                    | string    | First name of the individual                     |
| result.response.individual.middleName                   | string    | Middle name or initial                           |
| result.response.individual.lastName                     | string    | Last name of the individual                      |
| result.response.individual.addresses                    | array     | List of addresses associated with the individual |
| result.response.individual.addresses\[].address         | string    | Full formatted address                           |
| result.response.individual.addresses\[].extendedAddress | string    | Additional address details (apartment/unit)      |
| result.response.individual.addresses\[].city            | string    | City of residence                                |
| result.response.individual.addresses\[].region          | string    | State or region code                             |
| result.response.individual.addresses\[].postalCode      | string    | Postal or ZIP code                               |
| result.response.individual.ssn                          | string    | Social Security Number (SSN)                     |
| result.response.individual.dob                          | string    | Date of birth in YYYY-MM-DD format               |
| reason                                                  | string    | Overall API response message                     |
| code                                                    | string    | Response status code                             |

### Sample Error

:::CodeblockTabs
E601 Internal Server Error

```json
{
    "result": {},
    "reason": "Internal Server Error",
    "status": "failure",
    "code": "E601"
}
```

E001 Invalid regex&#x20;

```json
{
    "result": {},
    "reason": "Bad Request: \"ssn\" must be 9 digits",
    "code": "E001"
}
-----
{
    "result": {},
    "reason": "Bad Request: \"dob\" must be in YYYY-MM-DD",
    "code": "E001"
}
-----
{
    "result": {},
    "reason": "Bad Request: \"phoneNumber\" must start with +1 or 1 and be followed by exactly 10 digits.",
    "code": "E001"
}
-----
{
    "result": {},
    "reason": "Bad Request: \"email\" must be a valid email",
    "code": "E001"
}
----
{
    "result": {},
    "reason": "Bad Request: \"state\" length must be 2 characters long",
    "code": "E001"
}
----
{
    "result": {},
    "reason": "Bad Request: \"zip\" must be exactly 5 digits.",
    "code": "E001"
}

```

E401 Upstream Failure

```json
{
    "result": {},
    "reason": "Upstream error",
    "status": "failure",
    "code": "E401"
}
```

E001 Bad Request

```json
{
    "result": {},
    "status": "failure",
    "reason": "Bad Request",
    "code": "E001"
}
```

E301 Data Not Found

```json
{
    "result": {},
    "reason": "Data Not Found",
    "code": "E301"
}
```
:::

### Error Response Parameters

| **Parameter** | **Description**        |
| ------------- | ---------------------- |
| result        | Empty result object    |
| reason        | Reason for error       |
| status        | Status of the api      |
| code          | Error code from Signzy |

### Error Codes

| HTTP Status Code | Error Code | Description           |
| ---------------- | ---------- | --------------------- |
| 400              | E001       | Bad Request           |
| 401              | E1001      | Unauthorized Access   |
| 403              | E201       | Forbidden             |
| 404              | E301       | Data Not Found        |
| 409              | E401       | Upstream error        |
| 429              | E501       | Rate Limit Exceeded   |
| 500              | E601       | Internal Server Error |
| 503              | E701       | Service Unavailable   |
| 504              | E801       | Timeout               |

### Success Codes

| HTTP Status Code | Success Code | Description               |
| ---------------- | ------------ | ------------------------- |
| 200              | S001         | Request Successful.       |
| 200              | S003         | Data not Found on source. |

:::hint{type="info"}
### Getting help

Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.

You can reach out to us at [help@signzy.com](#). We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively.

We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you!
:::

