Lead Verify API

Overview

Use Whitepages Pro dynamic identity data to confidently verify lead authenticity. Lead verification made easy. In one simple query verify lead data like name, phone, email, and address info to validate the lead is a real person and can be contacted. Lead Verify confirms the name-to-phone, name-to-address, and name-to-email match from the lead. It also provides leading phone intelligence, such as line type for TCPA, carrier, pre-paid status, and demographic data, like age range and gender, to enhance lead handling.

Get a Free API Key Not a developer?

Request

Lead Verify can do up to 5 searches as part of a single query. You can provide as few or as many inputs in the query. We will only populate the components in the API return that correspond to the inputs provided.

A well-formatted request looks like:

Copy
https://proapi.whitepages.com/3.3/lead_verify.json?name=Drama+Number&phone=6464806649&email_address=medjalloh1@yahoo.com&address.street_line_1=302+Gorham+Ave&address.city=Ashland&address.postal_code=59004&address.state_code=MT&ip_address=108.194.128.165&api_key=KEYVAL

REQUEST PARAMETERS

ParametersDescriptionExamples
api_keySee here to acquire an API Key REQUIRED
nameThe complete name of a person or business

Jan Smith

firstnameFirst name of a person

Jan

lastnameLast name of a person

Smith

phonePhone 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

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

BR or MX

email_addressLead Verify supports all standard email addresses

example@gmail.com

ip_addressIPv4 IP addresses

192.0.2.1

address.street_line_1Primary address with number and street name to be searched

2808 Nero Blvd

address.street_line_2Apartment or other additional address information to be searched

Apt 265
Box 34Rs

address.cityCity

Seattle

address.postal_codePostal code. Can be 5- or 9- digit US or 6-digit Canadian zip code

92019 or S3D 3F3

address.state_code2 character state code

WA

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

CA or US

Please note, 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 Lead Verify request.

Response

A Lead Verify response consists of various checks based on the inputs entered. All possible components are below:

Phone Checks

The checks indicate whether the phone matches the input name provided on the lead, and whether the phone number is valid or not, and is currently in service at time of inquiry. The response also provides certain phone metadata attributes and subscriber’s demographic attributes that help prioritize the lead and manage TCPA compliance.

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

Phone Checks Response

1errorObject

Copy
error: null
An object containing a name and a message describing any issue encountered retrieving phone information.

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"
}
2warningArray

Copy
warnings: [ ]
A warning message that returns:

  • Invalid Input
  • Not found
  • "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:

  • true
  • false
  • null
4phone_contact_scoreInteger

Copy
phone_contact_score: 2
A 1-4 score on whether this is a valid phone number and matches to the input name provided for the lead. Score of 1 indicates a valid, connected number with the subscriber name matching to the input name provided with the lead. 4 indicates very high confidence that the lead cannot be cannot be reached via this phone. null score will be returned in case of an error.

5is_connectedBoolean

Copy
is_connected: null
Indicates whether the phone is connected or not in service. Possible values:

  • true
  • false
  • null
6phone_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
7subscriber_nameString

Copy
subscriber_name: "Drama Number"
Subscriber name of the input phone. null will be returned when subscriber name is unknown.

8subscriber_age_rangeString

Copy
subscriber_age_range: "30-34"
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+
9subscriber_genderString

Copy
subscriber_gender: "Male",
Subscriber’s gender can be:

  • Male
  • Female
  • null
10subscriber_addressArray

Copy
subscriber_address: {
street_line_1: "302 Gorham Ave",
street_line_2: "",
city: "Ashland",
postal_code: "59004",
state_code: "MT",
country_code: "US"
},
Full or partial address of the subscriber. Can include House Number, Street, City, State, Postal and Country.

11country_codeString

Copy
country_code: "US"
2 character country code for the input phone.

12line_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
  • null
13carrierString

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

14is_prepaidBoolean

Copy
is_prepaid: null
Indicates if the phone is associated with a prepaid account. Possible values:

  • true
  • false
  • null
15is_commercialBoolean

Copy
is_commercial: false
Indicates if the phone is registered to a business. Possible values:

  • true
  • false
  • null

A sample response:

Copy
phone_checks: {
error: null,
warnings: [ ],
is_valid: true,
phone_contact_score: 2,
is_connected: null,
phone_to_name: "Match",
subscriber_name: "Drama Number",
subscriber_age_range: "30-34",
subscriber_gender: null,
subscriber_address: {
street_line_1: "302 Gorham Ave",
street_line_2: "",
city: "Ashland",
postal_code: "59004",
state_code: "MT",
country_code: "US"
},
country_code: "US",
line_type: "Non-fixed VOIP",
carrier: "Twilio",
is_prepaid: null,
is_commercial: false
},

Address Checks

The check indicates whether the address is real and active and verifies if the resident matches the input name provided on the lead. In addition, if enabled for your plan, response also provides certain address metadata attributes and resident’s demographic attributes that can further help prioritize the leads.

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

Address Checks Response

1errorObject

Copy
error: null
An object containing a name and a message describing any issue encountered retrieving address information.

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
  • Not found
  • Missing unit/apt/suite number
  • Invalid unit/apt/suite number
  • "empty array"
3is_validBoolean

Copy
is_valid:true
A boolean value indicating if the address is a valid existing address. Possible values:

  • true
  • false
  • null
4diagnosticsArray

Copy
diagnostics: [ ]
A diagnostics message that contains additional information about the validity of the address. This field is used for international addresses only. 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
5address_contact_scoreInteger

Copy
address_contact_score: 1
A 1-4 score on whether this is a valid address and resident matches to the input name provided for the lead. Score of 1 indicates a valid address with the resident name matching to the input name provided with the lead. 4 indicates very high confidence that the lead cannot be reached via this address. null will be returned in case of an error

6is_activeBoolean

Copy
is_active: true
Indicates if the address is currently receiving mail. Possible values:

  • true
  • false
  • null
7address_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
8resident_nameString

Copy
resident_name: "Drama Number"
Resident name of the input address. null will returned in case when resident name is unknown.

9resident_age_rangeString

Copy
resident_age_range” "30-34"
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+
10resident_genderString

Copy
resident_gender: "Male"
Resident’s gender:

  • Male
  • Female
  • null
11typeString

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

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

Copy
is_commercial: false
Indicates if the address is a business address. Possible values:

  • true
  • false
  • null
13resident_phoneString

Copy
resident_phone: null
Landline phone associated with resident at the address. Will be returned when landline phone exists and is known by Whitepages, and there is an address to name match. Possible values:

  • Landline phone number
  • No phone found
  • null

A sample response:

Copy
address_checks: {
error: null,
warnings: [ ],
is_valid: true,
diagnostics: [ ],
address_contact_score: 1,
is_active: true,
address_to_name: "Match",
resident_name: "Drama Number",
resident_age_range: "30-34",
resident_gender: "Male",
type: "Unknown address type",
is_commercial: false,
resident_phone: "No phone found"
},

Email Address Checks

The check indicates whether the email is valid or malformed, active or inactive, and verifies if the email registered name matches the input name provided.

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

Email Address Checks Response

1errorObject

Copy
error: null
An object containing a name and a message describing any issue encountered retrieving email address information.

Following error object may be returned here.

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

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:

  • true
  • false
  • null
4diagnosticsArray

Copy
diagnostics: [
"Syntax OK, domain exists, and mailbox does not reject mail"
]
Diagnostic message for the is_valid flag. This is the reason 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
5email_contact_scoreInteger

Copy
email_contact_score: 3
A 1-4 score on whether this is a valid email address and matches to the input name provided for the lead. Score of 1 indicates a valid email with the registered name matching to the input name provided with the lead. 4 indicates very high confidence that the lead cannot be reached via this email.

6is_disposableBoolean

Copy
is_disposable: false
Indicates whether the email domain is disposable. Possible values:

  • true
  • false
  • null
7email_to_nameString

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

  • Match
  • No match
  • No name found
  • null
8registered_nameString

Copy
registered_name: "MOHAMED JALLOH"
Returns the name that we have on record for the supplied email. Possible values:

  • Actual name
  • No name found
  • null

A sample response:

Copy
email_address_checks: {
error: null,
warnings: [ ],
is_valid: true,
diagnostics: [
"Syntax OK, domain exists, and mailbox does not reject mail"
],
email_contact_score: 3,
is_disposable: false,
email_to_name: "No match",
registered_name: "MOHAMED JALLOH"
},

IP Address Check

The checks indicate whether the IP address is a proxy and verifies its location.

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

IP Address Checks Response

1errorObject

Copy
error: null
An object containing a name and a message describing any issue encountered retrieving IP address information.

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

Private range IP address is indicative of some network misconfiguration. You should never see a lead coming from a private IP range.

3is_validBoolean

Copy
is_valid: true
Indicates whether the IP address is valid. Possible values:

  • true
  • false
  • null
4is_proxyBoolean

Copy
is_proxy: null
Indicates whether the IP address is a known proxy. Possible values:

  • true
  • false
  • null
5geolocationObject

Copy
geolocation: {
postal_code: "29205",
city_name: "Columbia",
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.

6distance_from_addressInteger
Copy
distance_from_address: 1117 

Distance between the IP address and physical address in miles.

The longer the distance between the IP address and a lead’s physical address can be indicative of a poor quality lead.

7distance_from_phoneInteger
Copy
distance_from_phone: 1117 

Distance between the IP address and best known location for the lead’s phone number in miles.

The longer the distance between the IP address and a lead’s phone number can be indicative of a poor quality lead.

8connection_typeString

Copy
connection_type: "Corporate" 
Connection type of the IP address. Possible values:

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

A sample response:

Copy
ip_address_checks: {
error: null,
warnings: [ ],
is_valid: true,
is_proxy: null,
geolocation: {
postal_code: "29205",
city_name: "Columbia",
country_name: "United States",
continent_code: "NA",
country_code: "US"
},
distance_from_address: 1117,
distance_from_phone: 1117,
connection_type: "Corporate"
},