Overview
The PhoneValidatorUSA API provides real-time
phone number validation for US telephone numbers.
It is designed for applications that need to
check phone numbers programmatically.
In addition to validation status, the API can
return available line type, carrier, city, state
and Do Not Call status information.
The API uses a simple HTTP GET request and returns
the result as JSON.
Base URL:
https://www.phonevalidatorusa.com
Authentication
Every API request requires a valid API key.
Your API key identifies your account and
authorizes the request.
API Key Header
The recommended method is to send the API key
using the X-API-KEY HTTP header.
X-API-KEY: YOUR_API_KEY
Query Parameter
Alternatively, the API key can be supplied using
the apikey query parameter.
?apikey=YOUR_API_KEY
Keep your API key private. Do not expose it in
client-side JavaScript or publicly accessible
source code.
API Credits:
Each successfully processed phone validation request
consumes one API credit. The remaining credit balance
is returned in the credits_remaining field.
Invalid phone numbers do not consume a credit.
Endpoint
Use the following endpoint to check a phone number:
GET
/api/v1/validate/
Parameters
phone
Required
The US phone number to validate.
apikey
Optional
Your API key when authentication is supplied
through the query string instead of the
X-API-KEY header.
Example
/api/v1/validate/?phone=2025550123
Request Examples
Using X-API-KEY
GET /api/v1/validate/?phone=2025550123 HTTP/1.1
Host: www.phonevalidatorusa.com
X-API-KEY: YOUR_API_KEY
Using Query Parameter
GET /api/v1/validate/?phone=2025550123&apikey=YOUR_API_KEY
Response
A successful request returns a JSON response
containing the validation result and available
phone information.
{
"success": true,
"phone": "2025550123",
"is_dnc": false,
"status": "Valid",
"type": "Landline",
"carrier": "Example Carrier",
"city": "Washington",
"state": "DC",
"credits_remaining": 9842
}
Response Fields
|
Field
|
Type
|
Description
|
success
|
Boolean
|
Indicates whether the request
was successfully processed.
|
phone
|
String
|
The normalized US phone number.
|
status
|
String
|
The validation status returned
for the phone number.
|
type
|
String
|
The line type associated with
the phone number when available.
|
carrier
|
String
|
The carrier associated with
the phone number when available.
|
city
|
String
|
The city associated with the
phone number when available.
|
state
|
String
|
The US state associated with
the phone number when available.
|
is_dnc
|
Boolean
|
Indicates whether the phone
number is on the applicable
Do Not Call list.
|
credits_remaining
|
Integer
|
The number of API credits remaining in the account
after the current phone validation request.
|
Note:
City, state, line type and carrier information
may not be available for every phone number.
Errors
If a request cannot be processed, the API
returns a JSON response describing the error.
|
Error
|
Description
|
400
Missing parameters
|
The API key or phone number
was not supplied.
|
400
Invalid phone number
|
The supplied phone number is
not a valid US phone number.
|
401
Invalid API Key
|
The supplied API key is invalid
or does not match an API account.
|
403
API access is inactive
|
The API account is not currently active.
|
403
Insufficient credits
|
The account does not have enough
API credits to process the request.
|
500
Server error
|
The request could not be processed
due to an internal server or
database error.
|
Example Error
{
"success": false,
"error": "Invalid API Key"
}
Code Examples
cURL
curl -X GET "https://www.phonevalidatorusa.com/api/v1/validate/?phone=2025550123" ^
-H "X-API-KEY: YOUR_API_KEY"
JavaScript
fetch("https://www.phonevalidatorusa.com/api/v1/validate/?phone=2025550123", {
method: "GET",
headers: {
"X-API-KEY": "YOUR_API_KEY"
}
})
.then(response => response.json())
.then(data => console.log(data));
VB.NET
Dim client As New Net.WebClient()
client.Headers.Add("X-API-KEY", "YOUR_API_KEY")
Dim result As String =
client.DownloadString(
"https://www.phonevalidatorusa.com/api/v1/validate/?phone=2025550123")
Ready to Get Started?
Purchase API credits and get your API credentials
to start integrating US phone validation into your
application.
Purchase API Credits