Ready to get started? Once you have signed up and created an account try out a quick url search or curl command to query the Phone Validator RESTful API:
https://api.phonevalidator.com/api/v4/phonesearch?apikey={APIKEY}&phone={PHONE}&type={TYPE}®ion={REGION}
Note for security reasons that only secure HTTPS requests are supported.
In order to test the API without incurring charges, please use the following demonstration number: 7029270000
Sending a query using this number will return the following JSON response:
{
"PhoneNumber":"7029270000",
"Cost":0.004,
"SearchDate":"2026-03-02T22:04:01.2579252-07:00",
"StatusCode":"200",
"StatusMessage":"OK",
"PhoneBasic":
{
"PhoneNumber":"7029270000",
"ReportDate":"2026-03-02T22:04:01.2629238-07:00",
"LineType":"CELL PHONE",
"PhoneCompany":"T-MOBILE",
"PhoneLocation":"NORTH LAS VEGAS, NV",
"OutsideUS": "NO",
"Country":"UNITED STATES",
"CountryCode":"US",
"FakeNumber": "NO",
"FakeNumberReason": "",
"ErrorCode":"",
"ErrorDescription":""
}
}
Here's some basics to know:
- Authentication is always required. To simplify the examples, however, the documentation will frequently omit showing the query-string api key parameter.
- Your API key should not, in any circumstances, be shared with anyone else. Should your key be compromised, you will need to immediately request a new key, or cancel your account. You are responsible for any costs incurred while accessing the Api with your key.
- Phone numbers can be submitted with or without punctuation. We will remove all punctuation prior ro processing.
U.S., Canada and Caribbean countries do not require a country code or "leading 1", however they may include this if wanted. All other countries outside of the U.S. and Canada must include their country code. The E.164 + symbol may also be included, but is not required. You can include the "+" sign in the query string, but it must be URL encoded. Example: phone=%2B17029270000 or phone=%2B1702-927-0000
The Phone Validator API has a rate limit of 25 requests per second.
All Phone Validator API requests require authentication, by passing your api key as part of the query string parameters. You can verify you have API access and obtain your key by visiting your account information.
There are a few configuration options that you can specify via query-string when making a request to Phone Validator API.
You must authenticate by passing the apikey in the query string. Below you will find an example of authentication using the apikey parameter within the query string. This is a required value.
https://api.phonevalidator.com/api/v4/phonesearch?apikey={APIKEY}
The phone parameter can be in several formats and can include the leading 1 but is not required. (For example for you can use 17029270000 or 7029270000, 1-702-927-0000 or 702-927-0000.) This is a required value.
https://api.phonevalidator.com/api/v4/phonesearch?apikey={APIKEY}&phone={PHONE}
The type parameter indicates the phone lookup request type. There are two types of lookups - line type basic and fake. Line Type Basic (aka Basic) is our most popular search and includes line type information, phone carrier plus fake number information. Our Fake Number check (aka Fake) is our fake number information as a stand-alone option. This is a required value.
https://api.phonevalidator.com/api/v4/phonesearch?apikey={APIKEY}&phone={PHONE}&type=basic
https://api.phonevalidator.com/api/v4/phonesearch?apikey={APIKEY}&phone={PHONE}&type=fake
The region parameter indicates the phone lookup request region. There are three region options: 1, 2, or 3. Region 1 will search both the U.S. and outside the U.S.. Region 2 will search U.S. and Canada Only and will mark any numbers outside as fake. Region 3 will search Outside the U.S. and Canada Only, and any phone numbers from the U.S. or Canada will be automatically marked as Fake. If you don't know where your numbers are located or your numbers could be anywhere in the world including the U.S., use Region 1. This is a required value.
https://api.phonevalidator.com/api/v4/phonesearch?apikey={APIKEY}&phone={PHONE}&type=basic®ion=1
https://api.phonevalidator.com/api/v4/phonesearch?apikey={APIKEY}&phone={PHONE}&type=basic®ion=2
https://api.phonevalidator.com/api/v4/phonesearch?apikey={APIKEY}&phone={PHONE}&type=basic®ion=3
All responses are returned in JSON format. Following are examples of each response and corresponding fields returned.
The header result will contain phone number searched, cost for search, search date, status code, and status message.
"PhoneNumber":"7029270000",
"Cost":0.004,
"SearchDate":"2026-03-02T22:04:01.2579252-07:00",
"StatusCode":"200",
"StatusMessage":"OK"
The basic search will return phone number searched, line type, phone company, phone location, outside US, country, country code, fake number information, error code, and error description. Possible values for line type are CELL PHONE, LANDLINE, VOIP, TOLL-FREE, UNKNOWN OR FAKE. Any error that occurs for basic lookup will be indicated in the basic results.
"PhoneNumber":"7029270000",
"ReportDate":"2026-03-02T22:04:01.2629238-07:00",
"LineType":"CELL PHONE",
"PhoneCompany":"T-MOBILE",
"PhoneLocation":"NORTH LAS VEGAS, NV",
"OutsideUS": "NO",
"Country":"UNITED STATES",
"CountryCode":"US",
"FakeNumber":"NO",
"FakeNumberReason":"",
"ErrorCode":"",
"ErrorDescription":""
The fake search will return phone number searched, fake number, fake reason, error code, and error description. Possible values for fake number are YES or NO. Fake reason will include details if number is determined to be fake. Any error that occurs for fake lookup will be indicated in the fake results.
"PhoneNumber":"7029270000",
"ReportDate":"2026-03-02T22:04:01.2629238-07:00",
"FakeNumber":"NO",
"FakeNumberReason":"",
"ErrorCode":"",
"ErrorDescription":""
If there is an error then the phone, cost, search data, status code, status message, and empty results will be returned.
"PhoneNumber":"7029270000",
"Cost": 0,
"SearchDate": "2026-03-02T22:04:01.2629238-07:00",
"StatusCode": "503",
"StatusMessage": "UNAUTHORIZED",
"PhoneFake": null,
"PhoneBasic": null
When making Phone Validator API requests, there are several different HTTP status codes you may receive. If the status code is 200, everything is great. All other status codes indicate an error in processing the request.
200 OK
The request was successful.
429 TOO MANY REQUESTS
Too many request! We can only allow 25 calls per second.
500 UNEXPECTED ERROR
An unexpected error has occurred processing phone lookup.
501 BAD REQUEST
The phone number (e.g. format) isn't valid or is missing.
502 ACCOUNT NOT ACTIVE
The account is no longer active.
503 UNAUTHORIZED
The request was missing authentication or the credentials are not valid.
504 INSUFFICENT FUNDS
Authentication succeeded, but the account does not have enough funds available to complete the request.
Our team can be reached by submitting a contact request here.
Please note on July 10, 2020 V1 of our API was replaced by V2. API documentation for V1 can be found here. Please note new users may no longer consume our V1 API, however it will remain online indefinitely for those customers already using it. Please see the documentation above for the latest API version.
Please note on November 24, 2021 V2 of our API was replaced by V3. API documentation for V2 can be found here. Please note new users may no longer consume our V2 API, however it will remain online indefinitely for those customers already using it. Please see the documentation above for the latest API version.
Please note on March 18, 2026 V3 of our API was replaced by V4. API documentation for V3 can be found here. Please note new users may no longer consume our V3 API, however it will remain online indefinitely for those customers already using it. Please see the documentation above for the latest API version.