> ## 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.

# Lookup API

> Retrieve carrier, formatting, and portability information for phone numbers

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](https://cx.plivo.com/home).

***

## 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

```http theme={null}
GET https://lookup.plivo.com/v1/Number/{PhoneNumber}
```

Phone numbers must be in [E.164 format](https://en.wikipedia.org/wiki/E.164) (e.g., `+14155551234`).

### Query Parameters

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

### Example Request

```bash theme={null}
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

```json theme={null}
{
    "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         |

```json theme={null}
{
   "api_id": "<api_id>",
   "error_code": 403,
   "message": "Account is forbidden from accessing resource."
}
```

For a complete list of error codes, see [Troubleshooting](/lookup/troubleshooting/).

***

## Related

* [Postman Collection](/lookup/postman/) - Test the Lookup API with Postman
* [Troubleshooting](/lookup/troubleshooting/) - Error codes and solutions