---
title: Identity Fill
slug: us-apis/identity-fill
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 **Identity Fill API (US)** enables the retrieval of verified customer information using minimal input—such as a phone number, dob, or SSN etc. It is designed to streamline digital onboarding processes by auto-filling application forms with accurate personal data, thereby reducing friction, minimizing manual errors, and significantly enhancing the overall user experience.
This API is especially useful in scenarios where rapid, secure identity verification is needed with minimal effort from the end user.
### 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.
- Accelerate KYC (Know Your Customer) checks for regulatory compliance.
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-kyc/identity-fill' \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"consentStatus": "",
"phoneNumber": "",
"dob": "", // only one out of dob,ssn,last4 is allowed.
"ssn": "", // only one out of dob,ssn,last4 is allowed.
"last4": "", // only one out of dob,ssn,last4 is allowed.
"consentOptinType": "Whitelist",
"consentOptinMethod": "TCO",
"consentOptinDuration": "ONE",
"consentOptinId": "xxxxxx",
"consentOptinTimestamp": "2019-09-18T00:13:37.667Z",
“consentOptinUrl” : “www.example.com”
}'
```
:::
:::Tab{title="Pre-production"}
```curl
curl --location 'https://api-preproduction.signzy.us/api/v3/us-kyc/identity-fill' \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"consentStatus": "",
"phoneNumber": "",
"dob": "", // only one out of dob,ssn,last4 is allowed.
"ssn": "", // only one out of dob,ssn,last4 is allowed.
"last4": "", // only one out of dob,ssn,last4 is allowed.
"consentOptinType": "Whitelist",
"consentOptinMethod": "TCO",
"consentOptinDuration": "ONE",
"consentOptinId": "xxxxxx",
"consentOptinTimestamp": "2019-09-18T00:13:37.667Z",
“consentOptinUrl” : “www.example.com”
}'
```
:::
::::
### Request Body Parameters
| **Parameter** | **Data Type** | **Required** | **Description** |
| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| consentStatus | string | Required | The consent status of the phone number. Possible values are:
**optedIn** - The end user has provided consent for the collection of their personal data.
**optedOut **- The end user has refused to allow collection of their personal data.
**notCollected **- No attempt has been made to obtain consent from the end user.
**unknown** - The status of consent collection is unknown. |
| phoneNumber | string | Required | The phone number being queried.
Formats Accepted :-
1XXXXXXXXXX
+1XXXXXXXXXX |
| dob | string | Optional (Any one out of dob/ssn/last4 is required)
only one out of dob,ssn,last4 is allowed | Date of birth associated with the phone number.
Accepts format : ISO 8601 (YYYY-MM-DD) |
| ssn | string | Optional (Any one out of dob/ssn/last4 is required)
only one out of dob,ssn,last4 is allowed | Full 9 digits SSN number of the US citizen.
|
| last4 | string | Optional (Any one out of dob/ssn/last4 is required)
only one out of dob,ssn,last4 is allowed | Last 4 digit of SSN. |
| consentOptinType | string | Required | The type of opt-in.
Value should be "whitelist" here. |
| consentOptinMethod | string | Required | The method used to collect consent:
• TCO – online T\&C’s
• MA – mobile app
• TCP – paper T\&C’s
• IVR – via IVR
• SMS – text
• OTHER
|
| consentOptinDuration | string | Required | Indicates if consent is for single use or ongoing:
• ONE – single use
• ONG – ongoing
|
| consentOptinId | string | Required | A unique identifier for tracking the consumer’s opt-in. |
| consentOptinTimestamp | string | Required | Date/time when consent was obtained (ISO-8601 UTC format)
Example Format - \{2025-03-18T00:13:37.667Z} |
| consentOptinUrl | string | Optional | URL where the consumer provided consent (one-time) or URL of T\&C/Privacy Policy (ongoing). |
### Sample Response
```json
{
"result": {
"requestId": "686298439d153a6c45f6e725",
"description": "Success.",
"response": {
"phoneNumber": "12001001686",
"countryCode": "US",
"individual": {
"firstName": "Tod",
"middleName": "",
"lastName": "Weedall",
"addresses": [
{
"address": "39 South Trail",
"extendedAddress": "",
"city": "San Antonio",
"region": "TX",
"postalCode": "78285"
}
],
"ssn": "565228370",
"dob": "1984-12-10"
}
}
},
"reason": "Request Successful",
"code": "S001"
}
```
### Response Body Parameters
| **Parameter** | **Data Type** | **Description** |
| --------------- | ---------------- | --------------------------------------------------------------------------------------------- |
| requestId | string | The requestId from the request, reflected back for tracking purposes. |
| description | string | A text string that defines the cause of the status code. |
| **response** | object | An object containing the phone number and associated details. |
| phoneNumber | string | The phone number(s) associated with the individual. |
| countryCode | string | The country code. It will always be "US". |
| **individual** | object | The name object containing name details. |
| firstName | string | The first name of the individual associated with the phone number. |
| middleName | string | The middle name of the individual associated with the phone number. |
| lastName | string | The last name of the individual associated with the phone number. |
| **addresses** | array of objects | The address array containing address details.
It can contain multiple addresses objects. |
| address | string | The primary address line. Usually populated. |
| extendedAddress | string | The secondary address line. Populated for suites, apartments, boxes, departments, etc. |
| city | string | The city where the address is located. |
| region | string | The region or state where the address is located. |
| postalCode | string | The postal/zip code of the address. |
| dob | string | The date of birth associated with the phone number in YYYY-MM-DD format. |
| ssn | string | The social security number associated with the phone number. |
### Sample Error
:::CodeblockTabs
E601 Internal Server Error
```json
{
"result": {},
"reason": "Internal Server Error",
"code": "E601"
}
```
E001 Invalid regex
```json
{
"result": {},
"reason": "Bad Request: \"consentStatus\" must be one of [optedIn, optedOut, notCollected, unknown]",
"code": "E001"
}
-----
{
"result": {},
"reason": "Bad Request: \"dob\" must be in YYYY-MM-DD format",
"code": "E001"
}
-----
{
"result": {},
"reason": "Bad Request: \"phoneNumber\" with value \"\" fails to match the required pattern: /^(?:\\+?\\d{1,3}\\s?)?\\(?\\d{3}\\)?[\\s.]?\\d{3}[\\s.]?\\d{4}$/",
"code": "E001"
}
-----
{
"result": {},
"reason": "Bad Request: \"ssn\" with value \"\" fails to match the required pattern: /^(?!666|000|9\\d{2})\\d{3}(?!00)\\d{2}(?!0{4})\\d{4}$/",
"code": "E001"
}
-----
{
"result": {},
"reason": "Bad Request: \"last4\" with value \"\" fails to match the required pattern: /^\\d{4}$/",
"code": "E001"
}
```
E001 Empty Required field
```json
{
"result": {},
"reason": "Bad Request: \"phoneNumber\" is not allowed to be empty",
"code": "E001"
}
-----
{
"result": {},
"reason": "Bad Request: At least one of dob, ssn, or last4 is required",
"code": "E001"
}
```
E401 Upstream Failure
```json
{
"result": {},
"reason": "Upstream error",
"code": "E401"
}
```
E001 Bad Request
```json
{
"result": {},
"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 |
| 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. |
:::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!
:::