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
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 normalized country code

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

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 IP Addresses

192.0.2.1

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.

4is_connectedBoolean

Copy
"is_connected": true
Indicates whether the phone is connected or not in service. Possible values are True, False, or null.

 

Disconnected phone is a potential risk indicator and the.transaction should be flagged for further review.

5phone_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.

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.

8is_subscriber_deceasedBoolean
Copy
"is_subscriber_deceased": false

Indicates if the subscriber associated with the phone is deceased.

 

True is a risk indicator and the transaction should be flagged for manual review.

9country_codeString

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

10is_commercialBoolean

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

11line_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

12carrierString

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.

13is_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,
"is_connected": true,
"phone_to_name": "Match",
"phone_to_address": "Match",
"subscriber_name": "Fake Name",
"is_subscriber_deceased": false,
"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
  • Not found
  • "empty array"
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.

8is_resident_deceasedBoolean
Copy
"is_resident_deceased": false

Indicates if the resident associated with the address is deceased

 

True is a risk indicator and the transaction should be flagged for manual review

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.

10typeString

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",
"is_resident_deceased": false,
"is_commercial": 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
  • Timeout
  • General syntax error
  • Invalid character in address
  • Invalid domain syntax
  • Invalid username syntax
  • Invalid username syntax for that domain
  • Address is too long
  • Address has unbalanced parentheses, brackets, or quotes
  • Address does not have a username
  • Address does not have a domain
  • Address does not have an @ sign
  • Address has more than one @ sign
  • Invalid top-level-domain (TLD) in address
  • IP address not allowed as a domain
  • Comments are not allowed in email addresses
  • Unquoted spaces are not allowed in email addresses
  • Domain does not exist
  • Domain does not have a valid IP address
  • Domain cannot receive email
  • The mailbox is invalid or the username does not exist at the domain
  • Mailbox is full and can not receive email at this time
  • Mail is not accepted for this domain
  • Addresses with that username are not allowed
  • Addresses with that domain are not allowed
  • Address is a bot or other suppression
  • Address is a role-based account
  • Address is a known bouncer
  • Address is a spamtrap or known complainer
  • Address has opted out from commercial email
  • Internal error
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 cannot receive email and 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.

9email_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.

10email_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

11email_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.

12email_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"
"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"
},