Whitepages controls access to the API and data via an API Key. The API key is the primary data authentication method for your account. Also your usage is recorded and reported via the API Key. You can request the API key here.
Possible error responses for Whitepages Pro API requests and what they mean:
|HTTP CODE||ERROR NAME||Likely Cause|
|400||InvalidParametersError||Parameter called incorrectly|
|400||InputFieldError||Incorrect parameter information, such as non-existent area code on a phone number|
|400||InputError||No parameters given|
|400||Internal Error||If there is an internal error while performing the checks|
|401||Bad request||If ';' used as parameter separator in request. non UTF-8 encoded request|
|401||Not authorized||api_key parameter is not in the request|
|402||Payment required||API Key has exceeded its quota|
|403||AuthError||API Key is not authorized for that request or expired|
|403||QuotaExceededError||API Key has exceeded its quota|
|429||TooManyRequests||API Key has exceeded its rate limit|
|500||ServerUnavailable||Whitepages Pro API temporarily unavailable|
Pass Through Parameters
Developers can also pass custom parameters for tracking purposes. Typical scenarios we see customers use this feature for are:
- Know which department or specific customer of yours is making the queries
- Pass internal parameters, like OrderId, so that usage queries can later be tied to specific Whitepages Pro queries, allowing for easy review of historic decisioning.
We recommend using format like ‘__’ (double under score) or “customerName_parameterName” to future proof against parameters we might add. These parameters can be accessed as part of the JSON response for the Identity Check product. They can also be accessed via the Lookups report available for your account here:
How do I get an API Key?
We have multiple APIs available. To make sure you get the right key that fits your use case:
- for identity verification of orders and applications click here.
- for identifying unknown inbound calls or texts click here.
- for verifying incoming leads and if it is a real person click here.
- for phone intelligence based risk signals click here.
- for identifying and blocking phone spam click here.
- for querying by Person, Phone, Address or Business name click here.
How many calls can I make per second?
By default, as you sign up for the free API key, queries per second (qps) is rate limited to 4. As you move to a paid subscription, it can be increased to as high as 256 qps if needed.
How fast is the API response time?
Response times are as low as 0.2 secs for certain APIs but actual response times are dependent on the APIs you query.
The free queries allotment is not sufficient. is it possible to run a larger data test?
Please contact us at APISupport@whitepages.com and we will be happy to run a bigger data test for you.
How do I get my usage?
We are in the process of developing an API endpoint for the same. Stay tuned for more updates on this.
Where can I check the status of the service?
You can find the API status here.
How do you bill for API usage?
You are billed for each API call you make. The cost per API call depends on API query and volume.
What encryption options are available for Pro APIs?
Whitepages recommends all Pro API users interact with the system using HTTPS over TLS 1.2 using a high strength cipher, but supports HTTPS over TLS 1.1 as well.
Can I submit a request using POST method?
We recommend using GET for simplicity. POST is supported as well, in this case api_key must be part of the url and not in the request body
I have more questions, who can I contact?
Please email us at APISupport@whitepages.com.