Phone Intelligence API documentation
curl --request GET \
--url https://phoneintelligence.abstractapi.com/v1import requests
url = "https://phoneintelligence.abstractapi.com/v1"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://phoneintelligence.abstractapi.com/v1', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://phoneintelligence.abstractapi.com/v1",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://phoneintelligence.abstractapi.com/v1"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://phoneintelligence.abstractapi.com/v1")
.asString();require 'uri'
require 'net/http'
url = URI("https://phoneintelligence.abstractapi.com/v1")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"phone_number": "14159929960",
"phone_format": {
"international": "+14159929960",
"national": "(415) 992-9960"
},
"phone_carrier": {
"name": "T-Mobile",
"line_type": "mobile",
"mcc": 310,
"mnc": 160
},
"phone_location": {
"country_name": "United States",
"country_code": "US",
"country_prefix": "+1",
"region": "California",
"city": "San Francisco",
"timezone": "America/Los_Angeles"
},
"phone_messaging": {
"sms_domain": "tmomail.net",
"sms_email": "14159929960@tmomail.net"
},
"phone_validation": {
"is_valid": true,
"line_status": "active",
"is_voip": false,
"minimum_age": 1888
},
"phone_registration": {
"name": "Sergio Suarez",
"type": "consumer"
},
"phone_risk": {
"risk_level": "low",
"is_disposable": false,
"is_abuse_detected": false
},
"phone_breaches": {
"total_breaches": 1,
"date_first_breached": "2018-07-23",
"date_last_breached": "2018-07-23",
"breached_domains": [
{
"domain": "facebook.com",
"breach_date": "2019-07-23"
}
]
}
}
Popular APIs
Phone Intelligence API documentation
Endpoint reference for Abstract’s Phone Intelligence API: base URL, request parameters, response fields for carrier, line type, location, validation, risk and breach data, error codes and code samples.
GET
/
v1
Phone Intelligence API documentation
curl --request GET \
--url https://phoneintelligence.abstractapi.com/v1import requests
url = "https://phoneintelligence.abstractapi.com/v1"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://phoneintelligence.abstractapi.com/v1', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://phoneintelligence.abstractapi.com/v1",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://phoneintelligence.abstractapi.com/v1"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://phoneintelligence.abstractapi.com/v1")
.asString();require 'uri'
require 'net/http'
url = URI("https://phoneintelligence.abstractapi.com/v1")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"phone_number": "14159929960",
"phone_format": {
"international": "+14159929960",
"national": "(415) 992-9960"
},
"phone_carrier": {
"name": "T-Mobile",
"line_type": "mobile",
"mcc": 310,
"mnc": 160
},
"phone_location": {
"country_name": "United States",
"country_code": "US",
"country_prefix": "+1",
"region": "California",
"city": "San Francisco",
"timezone": "America/Los_Angeles"
},
"phone_messaging": {
"sms_domain": "tmomail.net",
"sms_email": "14159929960@tmomail.net"
},
"phone_validation": {
"is_valid": true,
"line_status": "active",
"is_voip": false,
"minimum_age": 1888
},
"phone_registration": {
"name": "Sergio Suarez",
"type": "consumer"
},
"phone_risk": {
"risk_level": "low",
"is_disposable": false,
"is_abuse_detected": false
},
"phone_breaches": {
"total_breaches": 1,
"date_first_breached": "2018-07-23",
"date_last_breached": "2018-07-23",
"breached_domains": [
{
"domain": "facebook.com",
"breach_date": "2019-07-23"
}
]
}
}
This page is the technical reference. For plans, the free tier and a live demo, see the Phone Validation API product page.
Getting started
REST
The Phone Intelligence API, like all of Abstract’s APIs, is organized around REST. It is designed to use predictable, resource-oriented URL’s and to use HTTP status codes to indicate errors.HTTPS
The Phone Intelligence API requires all communications to be secured TLS 1.2 or greater.API Versions
All of Abstract’s API are versioned. The Phone Intelligence API is currently on Version 1.Your API Key
Your API key is your unique authentication key to be used to access Abstract’s Phone Intelligence API. Note that each of Abstract’s API has a unique API key, so you will need different keys to access the Phone Intelligence and Email Reputation APIs, for example. You can send it as a query parameter or in anAuthorization header: see Authentication methods.
Base URL
https://phoneintelligence.abstractapi.com/v1/
Authentication methods
The Phone Intelligence API supports multiple ways to authenticate your requests. You can use whichever method best fits your application.Query parameter (default)
Pass your API key as a query parameter. This is the simplest method and is shown in the Getting Started example above.curl 'https://phoneintelligence.abstractapi.com/v1/?api_key=YOUR_UNIQUE_API_KEY&phone=14154582468'
Bearer token header
Instead of passingapi_key as a query parameter, you can send it in the Authorization header as a Bearer token. This keeps your API key out of URLs and server logs.
curl -X GET 'https://phoneintelligence.abstractapi.com/v1/?phone=14154582468' \
-H 'Authorization: Bearer YOUR_UNIQUE_API_KEY'
api_key from the query string. Only the phone parameter is needed.
Validation endpoint
Abstract’s Phone Intelligence API simply requires your unique API key and the phone number you’d like to check:https://phoneintelligence.abstractapi.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14154582468
{
"phone_number": "14159929960",
"phone_format": {
"international": "+14159929960",
"national": "(415) 992-9960"
},
"phone_carrier": {
"name": "T-Mobile",
"line_type": "mobile",
"mcc": 310,
"mnc": 160
},
"phone_location": {
"country_name": "United States",
"country_code": "US",
"country_prefix": "+1",
"region": "California",
"city": "San Francisco",
"timezone": "America/Los_Angeles"
},
"phone_messaging": {
"sms_domain": "tmomail.net",
"sms_email": "14159929960@tmomail.net"
},
"phone_validation": {
"is_valid": true,
"line_status": "active",
"is_voip": false,
"minimum_age": 1888
},
"phone_registration": {
"name": "Sergio Suarez",
"type": "consumer"
},
"phone_risk": {
"risk_level": "low",
"is_disposable": false,
"is_abuse_detected": false
},
"phone_breaches": {
"total_breaches": 1,
"date_first_breached": "2018-07-23",
"date_last_breached": "2018-07-23",
"breached_domains": [
{
"domain": "facebook.com",
"breach_date": "2019-07-23"
}
]
}
}
POST method
In addition to GET requests, you can send POST requests to the Phone Intelligence API. This is useful when you prefer to send parameters in the request body rather than the URL.POST with form-encoded data
Send bothapi_key and phone as form-encoded fields in the request body:
curl -X POST 'https://phoneintelligence.abstractapi.com/v1/' \
-d 'phone=14154582468' \
-d 'api_key=YOUR_UNIQUE_API_KEY'
POST with Bearer token and JSON body
Authenticate via theAuthorization header and send phone in a JSON request body:
curl -X POST 'https://phoneintelligence.abstractapi.com/v1/' \
-H 'Authorization: Bearer YOUR_UNIQUE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "phone": "14154582468" }'
phone field, plus country if you use it. Send the Content-Type: application/json header with a JSON body, otherwise the body is read as form data and phone is not detected.
Request parameters
Your unique API key. Note that each user has unique API keys for each of
Abstract’s APIs, so your Phone Validation API key will not work for your IP
Geolocation API, for example.
The country’s ISO code. Add this parameter to indicate the phone number’s country, and the API will append the corresponding country code to its analysis. For instance, add country=US to indicate that the phone number is from the United States.
Response parameters
The API response is returned in a universal and lightweight JSON format.The type of line. Possible values:
mobile, landline, voip, toll_free, personal, pager, unknown.Bulk upload (CSV)
Here are some best practices when bulk uploading a CSV file:- Ensure the first column contains the phone numbers to be analyzed.
- Remove any empty rows from the file.
- Include only one phone number per row.
- The maximum file size permitted is 50,000 rows.
Response and error codes
Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.| Code | Type | Details |
|---|---|---|
| 200 | OK | Everything worked as expected. |
| 400 | Bad request | Bad request. |
| 401 | Unauthorized | The request was unacceptable. Typically due to the API key missing or incorrect. |
| 422 | Quota reached | The request was aborted due to insufficient API credits. (Free plans) |
| 429 | Too many requests | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. |
| 500 | Internal server error | The request could not be completed due to an error on the server side. |
| 503 | Service unavailable | The server was unavailable. |