Making Your First Request
A beginner-friendly guide to making your first Whitepages API request
Ready to test your API key? You can try it right here in your browser, or follow the step-by-step guide using Postman.
Quick Test
Try It Now
Enter your API key below to make a test request and see real results.
Using Postman (No Code Required)
Postman is a free tool that lets you interact with APIs without writing code. Click the button below to import our pre-configured collection, or follow the manual setup steps.
What You'll Need
- Your Whitepages API key (received via email after signing up for a trial)
- Postman (free download)
Step-by-Step Guide
Download and Open Postman
Download Postman from postman.com/downloads and install it. Create a free account or skip sign-in to continue.
Create a New Request
- Click the + button to open a new request tab
- Make sure GET is selected in the dropdown (it's the default)
Enter the API URL
Paste this URL into the request field:
https://api.whitepages.com/v1/person?name=John%20Smith&city=Seattle&state_code=WAAdd Your API Key
- Click the Headers tab below the URL field
- In the Key column, enter:
X-Api-Key - In the Value column, paste your API key
Header Name is Case-Sensitive
Make sure to use X-Api-Key exactly as shown, with capital X, A, and K.
Send the Request
Click the Send button. You should see a JSON response in the panel below.
[
{
"id": "P1234567890",
"name": "John Smith",
"current_addresses": [
{
"address": "123 Main St, Seattle, WA 98101"
}
],
"phones": [
{
"number": "(206) 555-0198",
"type": "mobile"
}
]
}
]If you see data like this, your API key is working correctly.
Using cURL (Command Line)
If you prefer the command line, you can use cURL:
curl 'https://api.whitepages.com/v1/person?name=John%20Smith&city=Seattle&state_code=WA' \
--header 'X-Api-Key: YOUR_API_KEY'Replace YOUR_API_KEY with your actual API key.
Troubleshooting
403 Forbidden or "Invalid API Key"
- Double-check that you copied the entire API key from your email
- Verify the header name is exactly
X-Api-Key(case-sensitive) - Make sure there are no extra spaces before or after your API key
No Results Found
A 404 response with no results is normal—it means your API key is working, but no records matched your search. Try different search parameters.
Need Help?
Contact support@whitepages.com if you continue to have issues.
Next Steps
Now that you've made your first request, explore what else you can do: