Documentation Index
Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
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}
+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/+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)
| 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": "+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
| 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."
}
