Verify Data Based Identity Verification
With the Verify Data Based Identity Verification service, you can accesses and return consumer identities from thousands of databases for comprehensive coverage of US-based identities and non-US-based identities from select countries. The service returns match-level indicators for first name, last name, current addresses, Social Security or national identification number, date of birth, and mobile phone number. The service also compares submitted information of US-based identities to over 300 verification, validation, behavioral, relational, and known fraud alerts to assist in pinpointing suspicious and fraudulent identities.
You can use POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/dataBasedIdentityVerification to compare the unverified data submitted in the request body to the many databases and return a confidence level of the match, raw data from the vendor, and data from best match source if available.
You can also include Data Based Identity Verification in your Verify Policy.
Verify data based identity verification request data model
For US-based identities, the service requires at minimum for verification either name (or given_name and family_name) and national_id_number, which is a Social Security Number, or name (or given_name and family_name) and birth_date. Personally identifiable information (PII) is not returned unless Social Security Number or birth date are an exact match, and given name and family name are either a partial match or an exact match. PII is the bestMatch, creditBureau.subject.subjectRecord.indicative, and creditBureau.subject.subjectRecord.custom.idmanagerVerAnalysisV2.fraudAnalysis.location objects. If Social Security Number is not provided in requirements, it is not returned.
If phone is included in this request, it is not verified using SMS. This differs from the service behavior when DATA_BASED_IDENTITY_VERIFICATION is included in a verify policy.
| Property | Type | Required? | Mutable? | Description |
|---|---|---|---|---|
|
Object |
Required |
Mutable |
Contains two or more objects that contain information used by the service |
|
String |
Required |
Immutable |
Country code |
|
String |
Required |
Immutable |
Given name |
|
String |
Required |
Immutable |
Family name |
|
String |
Required/Optional |
Immutable |
Number and street portion of the address |
|
String |
Required/Optional |
Immutable |
Second line for street of the address |
|
String |
Required/Optional |
Immutable |
City portion of the address |
|
String |
Required/Optional |
Immutable |
State portion of the address |
|
String |
Required/Optional |
Immutable |
ZIP Code portion of the address |
|
String |
Optional |
Immutable |
Birth date |
|
String |
Required/Optional |
Immutable |
Social Security or national identifier number |
|
String |
Optional |
Immutable |
Mobile telephone number |
Verify data based identity verification response data model
Response data models differ by vendor:
Data Zoo response data model
Properties returned in serviceResponses.verifications and serviceResponses.returnedData vary by country.
| Property | Type | Required? | Mutable? | Description |
|---|---|---|---|---|
|
String |
N/A |
Read-only |
Two-character country code for the country. Refer to Groups for identities outside the US. |
|
String |
N/A |
Read-only |
Client reference, if given as input |
|
String |
N/A |
Read-only |
Reference number generated, which is unique to each transaction |
|
String |
N/A |
Read-only |
Returned with HTTP status code 400 when the request contains invalid or improperly formatted input data |
|
String |
N/A |
Read-only |
Match status. Can be |
|
String |
N/A |
Read-only |
Error message returned querying the data source |
|
Boolean |
N/A |
Read-only |
Whether or not an identity was verified against two or more independent data sources to reach a high level of confidence |
|
String |
N/A |
Read-only |
Search status. Can be |
|
Object |
N/A |
Read-only |
Object containing the responses from each service checked. Refer to serviceResponses overview. |
|
Integer |
N/A |
Read-only |
Status of all service responses. Can be: 0 - identityVerified TRUE, element verifications all TRUE; 1 - identityVerified TRUE, element verifications not all TRUE; 2 - identityVerified FALSE, sourceStatus SUCCESSFUL; 3 - identityVerified FALSE, sourceStatus NOT SUCCESSFUL |
|
String |
N/A |
Read-only |
Status of the verification source. Can be: |
|
String |
N/A |
Read-only |
Error message(s) from the data source, such as "Error querying data source" |
|
Boolean |
N/A |
Read-only |
Whether or not the identity is deemed verified |
|
String |
N/A |
Read-only |
Safe Harbour score. Refer to Safe Harbour Scores and Status. |
|
String |
N/A |
Read-only |
Score for matching name. Can be: |
|
String |
N/A |
Read-only |
Score for matching address. Can be: |
|
Object |
N/A |
Read-only |
Object that contains service-specific boolean indicators for individual verification checks |
|
Boolean |
N/A |
Read-only |
Whether or not full address element 1 matched |
|
Boolean |
N/A |
Read-only |
Whether or not full address element 2 matched |
|
Boolean |
N/A |
Read-only |
Whether or not full address element 3 matched |
|
Boolean |
N/A |
Read-only |
Whether or not full address element 4 matched |
|
Boolean |
N/A |
Read-only |
Whether or not full address element 5 matched |
|
Boolean |
N/A |
Read-only |
Whether or not bank verification number matched |
|
Boolean |
N/A |
Read-only |
Whether or not city matched |
|
Boolean |
N/A |
Read-only |
Whether or not the Brazilian national identity card matched |
|
Boolean |
N/A |
Read-only |
Whether or not the Mexican national identity card matched |
|
Boolean |
N/A |
Read-only |
Whether or not date of birth matched |
|
Boolean |
N/A |
Read-only |
Whether or not email matched |
|
Boolean |
N/A |
Read-only |
Whether or not email address matched |
|
Boolean |
N/A |
Read-only |
Whether or not first name matched |
|
Boolean |
N/A |
Read-only |
Whether or not full address matched |
|
Boolean |
N/A |
Read-only |
Whether or not full name matched |
|
Boolean |
N/A |
Read-only |
Whether or not gender matched |
|
Boolean |
N/A |
Read-only |
Whether or not land line phone number matched |
|
Boolean |
N/A |
Read-only |
Whether or not last name matched |
|
Boolean |
N/A |
Read-only |
Whether or not middle name matched |
|
Boolean |
N/A |
Read-only |
Whether or not national identification number matched |
|
Boolean |
N/A |
Read-only |
Whether or not phone number matched |
|
Boolean |
N/A |
Read-only |
Whether or not postal code matched |
|
Boolean |
N/A |
Read-only |
Whether or not state matched |
|
Boolean |
N/A |
Read-only |
Whether or not street matched |
|
Boolean |
N/A |
Read-only |
Whether or not voter number matched |
|
Object |
N/A |
Read-only |
Object that contains metadata, including |
|
String |
N/A |
Read-only |
Account class for Canada Residential |
|
String |
N/A |
Read-only |
Account type for Canada Residential |
|
String |
N/A |
Read-only |
Activation date for Canada Residential |
|
String |
N/A |
Read-only |
Full address of the individual. |
|
Object |
N/A |
Read-only |
Match score for each address element (if configured) |
|
String |
N/A |
Read-only |
Date of birth Matching Logic indicator (if configured) |
|
Object |
N/A |
Read-only |
Match score for each name element (if configured) |
|
String |
N/A |
Read-only |
Brand name for Canada Residential |
|
String |
N/A |
Read-only |
Carrier name for Canada Residential |
|
String |
N/A |
Read-only |
Data source type or category, such as telco or consumer |
|
String |
N/A |
Read-only |
Delivery Point Identifier of the address |
|
String |
N/A |
Read-only |
Full name of the individual - included or omitted based on the client’s configured settings |
|
String |
N/A |
Read-only |
National identification number from Denmark National ID service |
|
String |
N/A |
Read-only |
Person status from Denmark National ID service |
|
String |
N/A |
Read-only |
Phone status for Canada Residential |
|
Boolean |
N/A |
Read-only |
Flag indicating Deceased Check of the identity owner |
|
String |
N/A |
Read-only |
Identifies the data source used |
|
String |
N/A |
Read-only |
Subscriber identification number for Canada Residential |
|
String[] |
N/A |
Read-only |
Array of remarks regarding any encountered issues or pre-validation errors. |
serviceResponses Overview
Each service returns its own self-contained response block, ensuring modular and source-specific verification results. Consumers of this API should handle varying response structures dynamically based on the requested services.
Safe Harbour is the determination of verifying an identity owner against two independent data sources to reach a high level of confidence. A positive Safe Harbour Status can only be achieved when the identity owner’s name is verified in at least two independent sources, in combination with a verified address or a verified date of birth in the same two independent sources.
serviceResponses object
The serviceResponses object in the API response contains verification results from one or more data sources, structured under their respective service names. Each service returns a distinct response block with service-specific data.
Structure and behavior:
-
Each key within
serviceResponsescorresponds to aservice name, representing an individual verification source. -
Services may return data from a single source or multiple sources in a sequenced API call.
-
The structure of each service response varies, with fields such as
status,identityVerified, andsafeHarbourScorediffering between services. -
The
verificationsblock contains service-specific boolean indicators for individual verification checks such asaddressElement1,dateOfBirth,firstName. -
The
returnedDatablock provides metadata, includingcategoryandsource, indicating the data provider used for verification.
TransUnion response data model
Ping Identity reports confidence levels of verification as: HIGH, MEDIUM, and LOW. Refer to data object for DATA_BASED_IDENTITY_VERIFICATION + TRANSUNION for the correlation between confidence returned by this operation and the riskIndicator returned by Read One Verification Metadata.
| Property | Type | Required? | Mutable? | Description |
|---|---|---|---|---|
|
String |
N/A |
Read-only |
Confidence level of the match returned by the service. Can be |
|
Object |
N/A |
Read-only |
Contains the best match found for each property. |
|
String |
N/A |
Read-only |
City from the address. |
|
String |
N/A |
Read-only |
State from the address. |
|
String |
N/A |
Read-only |
Street from the address. |
|
String |
N/A |
Read-only |
ZIP Code from the address. |
|
String |
N/A |
Read-only |
Birthdate of the person. |
|
String |
N/A |
Read-only |
First name of the person. |
|
String |
N/A |
Read-only |
Last name of the person. |
|
String |
N/A |
Read-only |
Social Security number of the person. |
|
String |
N/A |
Read-only |
Phone. number of the person. |
|
Object |
N/A |
Read-only |
Contains the results from the credit bureau. |
|
String |
N/A |
Read-only |
Index of the subject. |
|
Object |
N/A |
Read-only |
Object containing the subject record. |
|
String |
N/A |
Read-only |
Index of the file. |
|
Object |
N/A |
Read-only |
Type of file entry. |
|
Boolean |
N/A |
Read-only |
Whether or not the data provider provided no response within 28 days. |
|
Boolean |
N/A |
Read-only |
Whether or not the person opted out of promotional offers. |
|
Boolean |
N/A |
Read-only |
Whether or not the person restricted access to their file. |
|
Boolean |
N/A |
Read-only |
Whether or not the person is a minor. |
|
Boolean |
N/A |
Read-only |
Whether or not the person disputes the file entry. |
|
String |
N/A |
Read-only |
Risk level. Can be |
|
String |
N/A |
Read-only |
The |
|
Integer |
N/A |
Read-only |
Numeric risk rating for the person equal to or greater than 0. |
|
Integer |
N/A |
Read-only |
Vendor-defined lower threshold of the medium risk verification point range, always 30. |
|
Integer |
N/A |
Read-only |
Vendor-defined upper threshold of the medium risk verification point range, always 49. |
|
Object[] |
N/A |
Read-only |
Array of key message objects. |
|
String |
N/A |
Read-only |
Code for the key message. |
|
String |
N/A |
Read-only |
Text for the key message. |
|
Object |
N/A |
Read-only |
Location of the person. |
|
String |
N/A |
Read-only |
Source of the county, such as |
|
String |
N/A |
Read-only |
Element from the input object used to find the location, such as |
|
String |
N/A |
Read-only |
Name of the county associated with the source |
|
String |
N/A |
Read-only |
Population bracket, such as |
|
String |
N/A |
Read-only |
Name of the city associated with the source |
|
String |
N/A |
Read-only |
Name of the state associated with the source |
|
String |
N/A |
Read-only |
Source of the ZIP Code, such as |
|
String |
N/A |
Read-only |
Element from the input object used to find the ZIP Code, such as |
|
String |
N/A |
Read-only |
ZIP Code associated with the source |
|
String |
N/A |
Read-only |
Whether the ZIP Code is literal or estimated. Can be |
|
String |
N/A |
Read-only |
Source of the region information, such as |
|
String |
N/A |
Read-only |
Result of comparing the source ZIP Code to the source city. Can be |
|
String |
N/A |
Read-only |
Result of comparing the source ZIP Code to the source state. Can be |
|
String |
N/A |
Read-only |
Result of comparing the source phone number to the source state. Can be |
|
String |
N/A |
Read-only |
Result of comparing the source phone number to the source ZIP Code. Can be |
|
String |
N/A |
Read-only |
Mileage between the phone number and ZIP Code. |
|
Object |
N/A |
Read-only |
Source of the employment information of the person, such as |
|
String |
N/A |
Read-only |
Whether or not the person disputes the file entry. |
|
Object |
N/A |
Read-only |
Location of the person. |
|
String |
N/A |
Read-only |
Source of the county, such as |
|
String |
N/A |
Read-only |
Element from the input object used to find the location, such as |
|
String |
N/A |
Read-only |
Name of the county associated with the source |
|
String |
N/A |
Read-only |
Population bracket, such as |
|
String |
N/A |
Read-only |
Name of the city associated with the source |
|
String |
N/A |
Read-only |
Name of the state associated with the source |
|
String |
N/A |
Read-only |
Source of the ZIP Code, such as |
|
String |
N/A |
Read-only |
Element from the input object used to find the ZIP Code, such as |
|
String |
N/A |
Read-only |
ZIP Code associated with the source |
|
String |
N/A |
Read-only |
Whether the ZIP Code is literal or estimated. Can be |
|
String |
N/A |
Read-only |
Source of the region information, such as |
|
String |
N/A |
Read-only |
Result of comparing the source ZIP Code to the source city. Can be |
|
String |
N/A |
Read-only |
Result of comparing the source ZIP Code to the source state. Can be |
|
String |
N/A |
Read-only |
Result of comparing the source phone number to the source state. Can be |
|
String |
N/A |
Read-only |
Result of comparing the source phone number to the source ZIP Code. Can be |
|
String |
N/A |
Read-only |
Mileage between the phone number and ZIP Code. |
|
String |
N/A |
Read-only |
Source of the distance, such as |
|
String |
N/A |
Read-only |
Minimum distance between home and business where the sub-element, |
|
String |
N/A |
Read-only |
Maximum distance between home and business where the sub-element, |
|
Object[] |
N/A |
Read-only |
Object containing the identification verification results for each data source used in the analysis. |
|
String |
N/A |
Read-only |
Source of the information, such as |
|
String |
N/A |
Read-only |
Status of the verification for this source. Can be |
|
String |
N/A |
Read-only |
First name verification results. Can be |
|
String |
N/A |
Read-only |
Middle name verification results. Can be |
|
String |
N/A |
Read-only |
Last name verification results. Can be |
|
String |
N/A |
Read-only |
Name suffix verification results. Can be |
|
String |
N/A |
Read-only |
Current address verification results. Can be |
|
String |
N/A |
Read-only |
Previous address verification results. Can be |
|
String |
N/A |
Read-only |
Phone number verification results. Can be |
|
String |
N/A |
Read-only |
Sodial Security number verification. Can be |
|
String |
N/A |
Read-only |
Date of birth verification results. Can be |
|
String |
N/A |
Read-only |
Vendor code for the add-on product. |
|
String |
N/A |
Read-only |
Status of the add-on product. Can be |
|
String |
N/A |
Read-only |
Source of the message, such as |
|
String |
N/A |
Read-only |
Vendor code for the alert. |
|
String |
N/A |
Read-only |
Text of the alert. |
|
String |
N/A |
Read-only |
Result of the subject search. Can be |
|
String |
N/A |
Read-only |
Specifies how returned messages are displayed in the response. Can be |
|
Object[] |
N/A |
Read-only |
Array of address objects, which shows addresses from various sources in chronological order. |
|
String |
N/A |
Read-only |
Type of address, such as |
|
String |
N/A |
Read-only |
Type of address as reported by USPS. |
|
Boolean |
N/A |
Read-only |
Whether or not the century is estimated. |
|
Boolean |
N/A |
Read-only |
Whether or not the day is estimated. |
|
Boolean |
N/A |
Read-only |
Whether or not the month is estimated. |
|
Boolean |
N/A |
Read-only |
Whether or not the year is estimated. |
|
String |
N/A |
Read-only |
Date the address was reported. |
|
String |
N/A |
Read-only |
City of the address. |
|
String |
N/A |
Read-only |
State of the address. |
|
String |
N/A |
Read-only |
ZIP Code or postal code of the address. |
|
String |
N/A |
Read-only |
A qualifier of the address, such as |
|
String |
N/A |
Read-only |
Source of the name, such as |
|
String |
N/A |
Read-only |
Status of the address, such as |
|
String |
N/A |
Read-only |
Name of the street. |
|
String |
N/A |
Read-only |
Number on the street. |
|
String |
N/A |
Read-only |
Type of street, such as |
|
String |
N/A |
Read-only |
Unit number at the address. |
|
String |
N/A |
Read-only |
Type of unit, such as |
|
String |
N/A |
Read-only |
Source of the date of birth, such as |
|
String |
N/A |
Read-only |
Age of the person. |
|
Object[] |
N/A |
Read-only |
Array of date of birth objects, which shows dates of birth from various sources. |
|
Boolean |
N/A |
Read-only |
Whether or not the century is estimated. |
|
Boolean |
N/A |
Read-only |
Whether or not the day is estimated. |
|
Boolean |
N/A |
Read-only |
Whether or not the month is estimated. |
|
Boolean |
N/A |
Read-only |
Whether or not the year is estimated. |
|
String |
N/A |
Read-only |
Source of the date of birth, such as |
|
String |
N/A |
Read-only |
Date the address was reported. |
|
String |
N/A |
Read-only |
Source of the gender, such as |
|
String |
N/A |
Read-only |
Gender of the person. |
|
Object[] |
N/A |
Read-only |
Array of name objects, which shows names from various sources. |
|
String |
N/A |
Read-only |
Given name of the person. |
|
String |
N/A |
Read-only |
Generational suffix of the person, such as |
|
String |
N/A |
Read-only |
Family name of the person. |
|
String |
N/A |
Read-only |
Middle name of the person. |
|
String |
N/A |
Read-only |
Source of the name, such as |
|
String |
N/A |
Read-only |
For business names, the type of name. |
|
Object[] |
N/A |
Read-only |
Array of phone number objects, which shows phone numbers from various sources. |
|
String |
N/A |
Read-only |
Area code of the phone number. |
|
String |
N/A |
Read-only |
Exchange of the phone number. |
|
String |
N/A |
Read-only |
A qualifier of the phone number, such as |
|
String |
N/A |
Read-only |
Suffix, or station number, of the phone number. |
|
String |
N/A |
Read-only |
Type of the phone number, such as |
|
String |
N/A |
Read-only |
Source of the phone number, such as |
|
Object[] |
N/A |
Read-only |
Array of Social Security number (SSN) objects, which shows SSNs from various sources. |
|
String |
N/A |
Read-only |
Oldest age of the range when the identification was issued. |
|
String |
N/A |
Read-only |
Youngest age of the range when the identification was issued. |
|
String |
N/A |
Read-only |
State in which the identification was issued. |
|
String |
N/A |
Read-only |
Status of the identification, such as |
|
String |
N/A |
Read-only |
Type of identification: |
|
String |
N/A |
Read-only |
Ending year of the range when the identification was issued. |
|
String |
N/A |
Read-only |
Starting year of the range when the identification was issued. |
|
Boolean |
N/A |
Read-only |
Whether or not the |
|
String |
N/A |
Read-only |
Social Security number. |
|
String |
N/A |
Read-only |
Source of the data shown, such as |