Identity Check API

Overview

Verify customer identities, screen applications for fraud, and assess the risk of a transaction. Whitepages Pro Identity Check is the only 5-query-in-1 identity verification solution on the market. In addition to providing rich data about each input, Identity Check performs the following cross-verifications:

1. email-to-name
2. phone-to-name
3. phone-to-address
4. address-to-name
5. IP geolocation-to-address
6. IP geolocation-to-phone

Get a Free API Key Not a developer?

Request

 

The Identity Check API can field up to two sets of inputs. You should submit specific parameters based on the amount of data you want to validate.

If you have one set of inputs:

  • primary.name
  • primary.phone
  • primary.address.street_line_1
  • primary.address.street_line_2 (optional, can include this as part of street_line_1)
  • primary.address.city
  • primary.address.state_code
  • primary.address.postal_code
  • primary.address.country_code
  • email_address
  • ip_address
  • api_key (required)

A well-formatted request with one set of inputs looks like:

Copy
https://proapi.whitepages.com/3.2/identity_check?primary.address.city=Ashland&primary.address.country_code=US&primary.address.postal_code=59004&primary.address.state_code=MT&primary.address.street_line_1=302+Gorham+Ave&primary.name=Drama+Number&primary.phone=6464806649&email_address=medjalloh1@yahoo.com&ip_address=64.124.61.215&api_key=API_KEY

If you have additional set of inputs, you can add secondary information:

  • secondary.name
  • secondary.phone
  • secondary.address.street_line_1
  • secondary.address.street_line_2 (optional, can include this as part of street_line_1)
  • secondary.address.city
  • secondary.address.state_code
  • secondary.address.postal_code
  • secondary.address.country_code

A well-formatted request with two sets of inputs looks like:

Copy
https://proapi.whitepages.com/3.2/identity_check.json?primary.name=Drama+Number&primary.phone=6464806649&primary.address.street_line_1=302+Gorham+Ave&primary.address.city=Ashland&primary.address.state_code=MT&primary.address.postal_code=59004&primary.address.country_code=US&secondary.name=Fake+Name&secondary.phone=6464806649&secondary.address.street_line_1=302+Gorham+Ave&secondary.address.city=Ashland&secondary.address.state_code=MT&secondary.address.postal_code=59004&secondary.address.country_code=US&email_address=medjalloh1@yahoo.com&ip_address=64.124.61.215&api_key=API_KEY

We will only populate the components in the API return that correspond to the inputs provided. For parameters where the option exists for data to be entered two ways, such as name or firstname and lastname, only one of those options should be used in an individual Pro Identity Check Request. We only support one email, one IP address, and one API key per request. Secondary information only applicable to name, phone, and address.

 

How to use primary and secondary parameters

IndustryPrimary/SecondaryUse case
Originations / Account SignupPrimary

Home Details

Secondary

Work Details

UnderwritingPrimary

Applicant-1 Details

Secondary

Applicant-2 Details

eCommerce / Card Not PresentPrimary

Billing Details

Secondary

Shipping Details

Small Business / Merchant verificationPrimary

Business Details

Secondary

Principal Home Details

Request parameters

ParametersDescriptionExamples
api_keySee here to acquire an API Key REQUIRED
transaction_idUnique internal transaction ID. Could be actual ID or hashed ID

fecba6c447b211e7a919

primary.nameComplete name of person to be compared only with names listed in primary information

Jan Smith

secondary.nameComplete name of person to be compared only with names listed in secondary information

Albert Foster

primary.firstnameFirst name of person to be compared only with first names listed in primary information

Jan

primary.lastnameLast name of person to be compared only with last names listed in primary information

Smith

secondary.firstnameFirst name of person to be compared only with first names listed in secondary information

Albert

secondary.lastnameLast name of person to be compared only with last names listed in secondary information

Foster

primary.address.street_line_1Primary address line 1 for building, street, and suffix.

1234 front ne

primary.address.street_line_2Optional. Primary address line 2 for apt, unit, or other info.

Apt 302

primary.address.cityPrimary city

Seattle

primary.address.postal_codePrimary postal code. Can be 5- or 9- digit US or 6-digit Canadian zip code

98101

primary.address.state_codePrimary 2 character state code

WA

primary.address.country_codePrimary alpha-2 country code. This parameter will be taken into account for primary input phone number validation when primary phone number is in local format and primary.phone.country_hint not present in the request

US or CA

secondary.address.street_line_1Secondary address line 1 for building, street, and suffix.

97 324th ave nw

secondary.address.street_line_2Optional. Secondary address line 2 for apt, unit, or other info.

Suite 36

secondary.address.citySecondary city

Denver

secondary.address.postal_codeSecondary postal code. Can be 5- or 9- digit US or 6-digit Canadian zip code

80205

secondary.address.state_codeSecondary 2 character state code

CO

secondary.address.country_codeSecondary normalized country code. This parameter will be taken into account for secondary input phone number validation when secondary phone number is in local format and secondary.phone.country_hint not present in the request

US or CA

primary.phonePrimary phone number in international or local format. The best format to use is E.164 as it guarantees consistent results.

+12066013561 (E.164) or
2069735184 or 12069735184 or 206-601-3561

primary.phone.country_hintOptional. 2 digit country code. To be used when you provide the primary phone number in local format

BR or MX

secondary.phoneSecondary phone number in international or local format. The best format to use is E.164 as it guarantees the consistent results.

+12066013561 (E.164)
2069735184 or 12069735184 or 206-601-3561

secondary.phone.country_hintOptional. 2 digit country code. To be used when you provide the secondary phone number in local format

BR or MX

email_addressPro Identity Check supports all standard email addresses

example@gmail.com

ip_addressIPv4 or IPv6 IP Addresses

192.0.2.1 or 2607:fb90:e95:6c14:0:9:e7f3:fc01

Response

 

An Identity Check response consists of various checks based on the inputs entered. All possible components are below:

Phone Checks

Includes primary_phone_checks, and secondary_phone_checks. These components indicate whether the phone is valid, provides metadata attributes, and verifies if the phone subscriber name matches the input name provided and if the phone location matches the input address provided.

Inputs considered:

  • primary.phone, primary.address, and primary.name (or primary.firstname and primary.lastname)
  • secondary.phone, secondary.address, and secondary.name (or secondary.firstname and secondary.lastname)

Click the # to see that field used within the example JSON response.

Phone Checks Response

1errorObject

Copy
"error": null
An error message for a phone check. Following error objects may be returned here.

Copy
{
"message": "Could not retrieve entire response",
"name": "PartialError"
}
Copy
{
"message": "_Phone number_ is international. You have international phone checks disabled for your API key.",
"name": "InternationalPhoneDisabled"
}
2warningsArray

Copy
"warnings": [ ]
A warning message that returns:

  • Invalid Input
  • Not found
  • Invalid county_hint value. Only Alpha-2 and Alpha-3 supported
  • "empty array"
3is_validBoolean

Copy
"is_valid": true
A boolean value indicating if the phone is a valid phone number and has been assigned to a carrier. Possible values are true, false or null.

4phone_to_nameString

Copy
"phone_to_name": "Match"
Verification result whether the subscriber name for the phone matches the input name. Possible values:

  • Match
  • No match
  • No name found
  • null

A match is a positive indicator and should allow clearing the transactions when used in conjunction with other signals.

 

A no match is a modest risk indicator. Additional testing needed for specific customer scenario to assign appropriate weighting.

5subscriber_age_rangeString

Copy
"subscriber_age_range": "65-69"
Subscriber’s age in a 5 year range, possible values: 18-24, 25-29, 30-34, 35-39, 40-44, 45-49, 50-54, 55-59, 60-64, 65-69, 70-74, 75-79, 80-84, 85-89, 90+.

6phone_to_addressString

Copy
"phone_to_address": "Match"
Verification result whether the address associated with the phone matches the input address. Possible values:

  • Match
  • Postal match
  • Zip+4 match
  • City/State match
  • No match
  • null

A match are positive indicators and should allow clearing the transactions when used in conjunction with other signals.

 

A no match is a modest risk indicator, but also can be result of family plans or phones belonging to a business.

7subscriber_nameString

Copy
"subscriber_name": "Fake Name"
Subscriber name of the input phone.

8country_codeString

Copy
"country_code": "US"
Country code for the input phone.

9is_commercialBoolean

Copy
"is_commercial": false
Indicates if the phone is registered to a business. Possible values are true, false, or null.

10line_typeString

Copy
"line_type": "Non-fixed VOIP"
Line type for the input phone. Possible values:

  • Mobile
  • Landline
  • Fixed VOIP
  • Non-fixed VOIP
  • Premium
  • Tollfree
  • Voicemail
  • Other
  • Unknown

Mobile, Fixed VOIP (E.g. Comcast or other cable provider of phone where phone number is fixed to a physical address) are positive indicators and should allow clearing the transaction when used in conjunction with other signals

 

Non-Fixed VOIP, Tollfree number is a risk indicator and the transaction should be flagged for further review

11carrierString

Copy
"carrier": "Twilio"
The company that provides voice and/or data services for this phone number. Carriers are returned at the MVNO level.

 

Certain carriers correlate well as a potential risk signal. Please contact us APISupport@whitepages.com to learn more.

12is_prepaidBoolean

Copy
"is_prepaid": null
Indicates if the phone is associated with a prepaid account. Possible values are True, False, or null.

 

Depending on your business, prepaid phones can be a strong risk indicator (i.e. selling luxury goods). Some businesses, like prepaid credit card providers, would view a prepaid phone as a positive signal that the transaction is not fraudulent.

A sample response:

Copy
"primary_phone_checks": {
"error": null,
"warnings": [ ],
"is_valid": true,
"phone_to_name": "Match",
"phone_to_address": "Match",
"subscriber_name": "Fake Name",
"subscriber_age_range": "65-69",
"country_code": "US",
"is_commercial": false,
"line_type": "Non-fixed VOIP",
"carrier": "Twilio",
"is_prepaid": null
},

Address Checks

Includes primary_address_checks, and secondary_address_checks. These components indicate whether the input addresses are real and active and verifies if the resident matches the input names provided.

Inputs considered:

  • primary.address and primary.name (or primary.firstname and primary.lastname)
  • secondary.address and secondary.name (or secondary.firstname and secondary.lastname)

Click the # to see that field used within the example JSON response.

Address Checks Response

1errorObject

Copy
"error": null
An error message for an address check.
Following error objects may be returned here.

Copy
{
"message": "Could not retrieve entire response",
"name": "PartialError"
}
Copy
{
"message": "_Address_ is international. You have international address checks disabled for your API key.",
"name": "InternationalAddressDisabled"
}
2warningsArray

Copy
warnings: [ ]
A warning message that returns:

  • Invalid Input
  • Invalid Country Code
  • Missing unit/apt/suite number
  • Invalid unit/apt/suite number
  • Input postal code was corrected. Potential impact to AVS code.
  • Not found
3is_validBoolean

Copy
"is_valid": true
A boolean value indicating if the address is a valid existing address. Possible values are true, false, and null.

 

If false, this is a potential risk indicator and the transaction should be flagged for further review

4diagnosticsArray
Copy
"diagnostics": ["Validated"]

A message to describe the level of validation done for international address or null. Possible values are

  • Validated
  • Validated with corrections
  • Validated only Street, Postcode, City, Country. Premise not validated
  • Validated only Postcode, City, Country
  • Validated only City, Country
  • Validated only Country
5is_activeBoolean

Copy
"is_active": true
Indicates if the address is currently receiving mail. Possible values are true, false, or null.

 

If false, USPS cannot deliver to this address or this address is not receiving mail currently. Such transactions should be flagged for further review

6address_to_nameString

Copy
"address_to_name": "Match"
Verification result whether the resident name for the address matches the input name. Possible values:

  • Match
  • No match
  • No name found
  • null

A match is a positive indicator and should allow clearing the transactions when used in conjunction with other signals.

 

A no match is a modest risk indicator. Additional testing needed for specific customer scenario to assign appropriate weighting.

7resident_nameString

Copy
"resident_name": "Fake Name"
Resident name of the input address.

8resident_age_rangeString

Copy
"resident_age_range": "65-69"
Resident’s age in a 5 year range, possible values: 18-24, 25-29, 30-34, 35-39, 40-44, 45-49, 50-54, 55-59, 60-64, 65-69, 70-74, 75-79, 80-84, 85-89, 90+.

9is_commercialBoolean

Copy
"is_commercial": false
Indicates if the address is a business address. Possible values are true, false, or null.

 

When shipping physical goods, commercial addresses are typically a positive signal and indicate that the order is not fraudulent.

10is_forwarderboolean

Copy
"is_forwarder": false
Indicates whether an address is performing freight forwarding or reshipping services.

  • true
  • false
  • null

Forwarders most likely will send the goods outside of the country.

11typeString

Copy
"type": "Single unit"
Indicates delivery point for the address. Possible values:

  • Commercial mail drop
  • Multi unit
  • Single unit
  • PO box
  • PO box throwback
  • Unknown address type

Commercial mail drop, PO Box and PO Box Throwback are potential risk indicators and the transaction should be flagged for further review

A sample response:

Copy
 "primary_address_checks": {
"error": null,
"warnings": [ ],
"is_valid": true,
"diagnostics": [],
"is_active": true,
"address_to_name": "Match",
"resident_name": "Fake Name",
"resident_age_range": "65-69",
"is_commercial": false,
"is_forwarder": false,
"type": "Single unit"
},

Email Address Checks

The check name here is email_address_checks. This component indicates whether the email is valid and active and verifies if the email registered name matches the input names provided. We also return intelligence about the age of the email address and domain.

Inputs considered:

  • email_address and primary.name (or primary.firstname and primary.lastname), or
  • email_address, secondary.name (or secondary.firstname and secondary.lastname)

Click the # to see that field used within the example JSON response.

Email Address Checks Response

1errorObject

Copy
"error": null
An error message for an email check.
Following error object may be returned here.

Copy
{
"message": "Could not retrieve entire response",
"name": "PartialError"
}
2warningsArray

Copy
"warnings": [ ]
A warning message that returns:

  • The mailbox is invalid or does not exist
  • General syntax error
  • Invalid domain syntax
  • Invalid username syntax
  • Address is too long
  • Invalid top-level-domain (TLD) in address
  • Domain does not exist
3is_validBoolean

Copy
"is_valid": true
Indicates whether the email address is valid and email deliverable. Possible values are true, false, or null.

 

If false, this is a potential risk indicator and the transaction should be flagged for further review

4diagnosticsArray

Copy
"diagnostics": ["Syntax OK, domain exists, and mailbox does not reject mail"]
Diagnostic message for the is_valid flag. These are the reasons why we call the email valid.

Valid messages:

  • Domain does not support validation (accepts all mailboxes)
  • Syntax OK and domain valid according to the domain database
  • Syntax OK, domain exists, and mailbox does not reject mail

‘Syntax OK, domain exists, and mailbox does not reject mail’ is a positive indicator and allow clearing the transaction when used in conjunction with other signals

5is_autogeneratedBoolean

Copy
"is_autogenerated": false
Indicates whether the email is potentially auto generated. Possible values are true, false, or null.

 

If true, this is a potential risk indicator and such transactions should be flagged for further review

6is_disposableBoolean

Copy
"is_disposable": false
Indicates whether the email domain is disposable. Possible values are true, false, or null.

 

Disposable emails are generally associated with fraudulent activities. If true, this is one of the strongest risk indicators and the transaction should be flagged for further review

7email_to_nameString

Copy
"email_to_name": "Match"
Verification result whether the registered name for the email matches the input name. Possible values:

  • Match
  • No match
  • No name found
  • null

A match is a positive indicator and should allow clearing the transactions when used in conjunction with other signals.

 

A no match is a modest risk indicator. Additional testing needed for specific customer scenario to assign appropriate weighting.

8registered_nameString

Copy
"registered_name": "Fake Name"
Returns the name that we have on record for the supplied email.

9registered_owner_age_rangeString

Copy
"registered_owner_age_range": "65-69"
Registered owner’s age in a 5 year range, possible values: 18-24, 25-29, 30-34, 35-39, 40-44, 45-49, 50-54, 55-59, 60-64, 65-69, 70-74, 75-79, 80-84, 85-89, 90+.

10email_first_seen_dateDate

Copy
"email_first_seen_date": "2007-07-11"
Date when the email was first seen.

 

The earlier the email seen date is, the better signal of the transaction being good when used in conjunction with other signals.

11email_first_seen_daysInteger

Copy
"email_first_seen_days": 3054
Days since when the email was first seen.

 

The greater the number of days, the better the signal of the transaction being good when used in conjunction with other signals. Typical buckets during risk analysis are:
New (< 90 days)
Established (Between 90 and 720 days)
Well Established (Over 720 days)

 

New bucket is a potential risk indicator and the transaction should be flagged for further review

12email_domain_creation_dateDate

Copy
"email_domain_creation_date": "1995-01-18"
Date when the email domain was created.

 

The earlier the email domain creation date is, the better signal of the transaction being good when used in conjunction with other signals.

13email_domain_creation_daysInteger

Copy
"email_domain_creation_days": 7611
Days since when the email domain was created.

 

The greater the number of days, the better the signal of the transaction being good when used in conjunction with other signals. Typically an email where the domain has been created less than 30 days ago is a risk indicator and the transaction should be flagged for further review

A sample response:

Copy
"email_address_checks": {
"error": null,
"warnings": [ ],
"is_valid": true,
"diagnostics": ["Syntax OK, domain exists, and mailbox does not reject mail"],
"is_autogenerated": false,
"is_disposable": false,
"email_to_name": "Match",
"registered_name": "Fake Name",
"registered_owner_age_range": "65-69"
"email_first_seen_date": "2007-07-11",
"email_first_seen_days": 3054,
"email_domain_creation_date": "1995-01-18",
"email_domain_creation_days": 7611
},

IP Address Check

The check name here is ip_address_checks. This component indicates whether the IP address is a proxy, returns the location of the IP, calculates the distance between the IP geolocation and the closest input address, and calculates the distance between the IP geolocation and closest input phone number

Inputs considered:

  • ip_address and primary.address/secondary.address,
  • ip_address, primary.phone/secondary.phone

Click the # to see that field used within the example JSON response.

IP Address Check Response

1errorObject

Copy
"error": null
An error message for an IP check.
Following error objects may be returned here.

Copy
{
"message": "Could not retrieve entire response",
"name": "PartialError"
}
2warningsArray

Copy
"warnings": [ ]
A warning message that returns:

  • Invalid Input
  • IP address is in private range
  • "empty array"

While private range IP address is not a huge risk signal on it is own. It is indicative of some network misconfiguration. You should never see a customer coming from a private IP range.

3is_validBoolean

Copy
"is_valid": true
Indicates whether the IP address is valid. Possible values are true, false, or null.

4geolocationObject

Copy
"postal_code": "10009",
"city_name": "New York",
"country_name": "United States",
"continent_code": "NA",
"country_code": "US"

Location of the IP address. Includes postal_code, city_name, country_name, continent_code, and country_code when available.

5is_proxyBoolean

Copy
"is_proxy": false
Indicates whether the IP address is a known proxy. Possible values are true, false, or null.

 

A proxy IP is a strong risk indicator and the transaction should be flagged for further review

6distance_from_addressInteger

Copy
"distance_from_address": 1117
Distance in miles between the IP address and closest physical address.

 

Longer the distance between the IP address where the transaction is happening and the primary or secondary address provided, the stronger risk indicator. Typically IP to address more than 100 miles should be flagged for further review.

7distance_from_phoneInteger

Copy
"distance_from_phone": 55

Distance in miles between the IP address and closest phone location (primary or secondary)

8connection_typeString
Copy
"connection_type": "cellular"

Connection type of the IP address. Possible values:

  • Cable/DSL
  • Corporate
  • Cellular
  • Dialup
  • null

Depending on the transaction type, one of group of values can be positive/risk indicators.

A sample response:

Copy
"ip_address_checks": {
"error": null,
"warnings": [ ],
"is_valid": true,
"geolocation": {
"postal_code": "10009",
"city_name": "New York",
"country_name": "United States",
"continent_code": "NA",
"country_code": "US"
},
"is_proxy": false,
"distance_from_address": 1117,
"distance_from_phone": 55,
"connection_type": "cellular"
},

Identity Check Confidence Score

The check name here is identity_check_score. The Confidence Score provides a comprehensive assessment of a transaction by leveraging the millions of transactional patterns across our network and the power of Identity Check’s 70+ data elements in a single, actionable score—made possible by sophisticated data analysis and machine learning models. The core strength of the score is that it reflects real life transaction outcomes based on the feedback information we get from our customers. We also see signals across our network and calculate multiple proprietary inputs such as identity element velocities, transactional frequencies, and linkage histories.

To return a score, we need at least two inputs from the following:

  • Name (primary or secondary)
  • Phone (primary or secondary)
  • Address (primary or secondary)
  • Email address or IP address 

Identity Check Confidence Score

1identity_check_scoreInteger
Copy
"identity_check_score": 446

The score ranges from 0 to 500. In general, a higher number score indicates a riskier transaction, while a lower number indicates a good transaction.