Lookup API - Plivo

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: USD 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

Name	Type	Description
`type`	string	Set to `carrier` to retrieve carrier information

Example Request

curl -X GET "https://lookup.plivo.com/v1/Number/+14151234567?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)

Attribute	Type	Description
`api_id`	string	Unique request identifier
`phone_number`	string	The phone number in E.164 format
`country`	object	Country information: `name`, `iso2`, `iso3`
`format`	object	Number formats: `e164`, `national`, `international`, `rfc3966`
`carrier`	object	Carrier details (see below)
`resource_uri`	string	URI to look up the same number again

Carrier Object

Attribute	Type	Description
`mobile_country_code`	string	MCC (empty for fixed numbers)
`mobile_network_code`	string	MNC (empty for fixed numbers)
`name`	string	Carrier name
`type`	string	`fixed`, `mobile`, `voip`, `toll-free`, or `unknown`
`ported`	string	`yes`, `no`, or `unknown` (US/Canada only)

Success Example

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

Error Response

Attribute	Type	Description
`api_id`	string	Unique request identifier
`error_code`	integer	Error code
`message`	string	Error description

{
   "api_id": "<api_id>",
   "error_code": 403,
   "message": "Account is forbidden from accessing resource."
}

For a complete list of error codes, see Troubleshooting.

Postman Collection - Test the Lookup API with Postman
Troubleshooting - Error codes and solutions

​Prerequisites

​Authentication

​Look Up a Phone Number

​Request

​Query Parameters

​Example Request

​Response

​Success Response (HTTP 200)

​Carrier Object

​Success Example

​Error Response

​Related