Skip to main content
The Lookup API provides a way to retrieve information about a phone number:
  • Region-specific number formatting and validation
  • Carrier and service provider information
  • Portability information (US and Canada only)
Pricing: $0.004 per request

​
Prerequisites

You need your Plivo Auth ID and Auth Token, which you can find on the Plivo console.

​
Authentication

Lookup API requests are protected with HTTP Basic authentication. Use your Plivo auth_id as the username and auth_token as the password.

​
Look Up a Phone Number

Retrieve carrier and formatting information for a phone number.

​
Request

GET https://lookup.plivo.com/v1/Number/{PhoneNumber}
Phone numbers must be in E.164 format (e.g., +14155551234).

​
Query Parameters

NameTypeDescription
typestringSet to carrier to retrieve carrier information

​
Example Request

curl -X GET "https://lookup.plivo.com/v1/Number/+16172252821?type=carrier" \
  -u "AUTH_ID:AUTH_TOKEN"

​
Response

Returns a JSON response with an api_id that uniquely identifies the request.

​
Success Response (HTTP 200)

AttributeTypeDescription
api_idstringUnique request identifier
phone_numberstringThe phone number in E.164 format
countryobjectCountry information: name, iso2, iso3
formatobjectNumber formats: e164, national, international, rfc3966
carrierobjectCarrier details (see below)
resource_uristringURI to look up the same number again

​
Carrier Object

AttributeTypeDescription
mobile_country_codestringMCC (empty for fixed numbers)
mobile_network_codestringMNC (empty for fixed numbers)
namestringCarrier name
typestringfixed, mobile, voip, toll-free, or unknown
portedstringyes, no, or unknown (US/Canada only)

​
Success Example

{
    "api_id": "e4a25a0a-a19f-4ff6-b8b5-1841bea253f6",
    "phone_number": "+16172252821",
    "country": {
        "name": "United States",
        "iso2": "US",
        "iso3": "USA"
    },
    "format": {
        "e164": "+16172252821",
        "national": "(617) 225-2821",
        "international": "+1 617-225-2821",
        "rfc3966": "tel:+1-617-225-2821"
    },
    "carrier": {
        "mobile_country_code": "",
        "mobile_network_code": "",
        "name": "Verizon",
        "type": "fixed",
        "ported": "no"
    },
    "resource_uri": "/v1/Number/+16172252821?type=carrier"
}

​
Error Response

AttributeTypeDescription
api_idstringUnique request identifier
error_codeintegerError code
messagestringError description
{
   "api_id": "<api_id>",
   "error_code": 403,
   "message": "Account is forbidden from accessing resource."
}
For a complete list of error codes, see Troubleshooting.