> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# Look up phone number

GET https://%7BYour_Space_Name%7D.signalwire.com/api/relay/rest/lookup/phone_number/{e164_number}

Returns validity and formatting information for any supplied E.164 phone number, with optional carrier and caller-name data. Use it to normalize or enrich a number before other workflows; it neither searches purchasable inventory nor returns numbers owned by the project. Use [Search phone numbers](/docs/apis/rest/phone-numbers/search-available-phone-numbers) or [List phone numbers](/docs/apis/rest/phone-numbers/list-phone-numbers) for those jobs.

#### Permissions

No API token scope is required to make a successful request to this endpoint.

[Learn more about API scopes](/docs/platform/your-signalwire-api-space).

Reference: https://signalwire.com/docs/apis/rest/phone-number-lookup/lookup-phone-number

## Authentication

- `Authorization` header (basic auth, required) — SignalWire Basic Authentication using Project ID and API Token. The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password. Example: ``` Authorization: Basic base64(project_id:token) ```

## Request

### Path parameters

- `e164_number` (string, required) — The phone number in E.164 format.

### Query parameters

- `include` (string, optional) — Further number information to include in the response, some of which are billable. You can specify: carrier (Lookup full carrier information for the number), cnam (Lookup Caller ID information for the number). Separate multiple values with a comma: include=carrier,cnam.

## Response

### 200

The request has succeeded.

- `country_code_number` (integer, optional) — The Country code associated with the number.
- `national_number` (string, optional) — Number in the countries national format.
- `possible_number` (boolean, optional) — Whether the number supplied is a possible number.
- `valid_number` (boolean, optional) — Whether the number supplied is a valid number.
- `national_number_formatted` (string, optional) — The E164 number formatted in national format.
- `international_number_formatted` (string, optional) — The E164 number formatted in international format.
- `e164` (string, optional) — The number in E164 format.
- `location` (string, optional) — The location of the number based on its area code and NPA.
- `country_code` (string, optional) — The ISO3166 alpha 2 country code associated with the number.
- `timezones` (list of string, optional) — The time zones associated with the number.
- `number_type` (string, optional) — The type of number based on its area code and NPA.
- `carrier` (object, optional) — Carrier information. Adding include=carrier to your request will do a live lookup to determine the current carrier information about this number.
  - `lrn` (string, optional) — The LRN associated with the number.
  - `spid` (string, optional) — The Service Profile Identifier associated with the number.
  - `ocn` (string, optional) — The Operating Company Number associated with the number.
  - `lata` (string, optional) — The Local Access and Transport Area number associated with the number.
  - `city` (string, optional) — The City associated with the number.
  - `state` (string, optional) — The State/Province/Region associated with the number.
  - `jurisdiction` (string, optional) — The Jurisdiction associated with the number.
  - `lec` (string, optional) — The LEC or Carrier of the number.
  - `linetype` (string, optional) — The type of line the number is. Generally either wireless or landline.
- `cnam` (object, optional) — Caller ID information. Adding include=cnam to your request will do a live lookup to determine the current caller ID information about this number.
  - `caller_id` (string, optional) — The caller ID associated with the number.

## Examples

**Response**

```json
{
  "country_code_number": 1,
  "national_number": "5551234567",
  "possible_number": true,
  "valid_number": true,
  "national_number_formatted": "(555) 123-4567",
  "international_number_formatted": "+1 555-123-4567",
  "e164": "+15551234567",
  "location": "Texas",
  "country_code": "US",
  "timezones": [
    "string"
  ],
  "number_type": "Fixed Line or Mobile",
  "carrier": {
    "lrn": "15551234567",
    "spid": "683X",
    "ocn": "12345",
    "lata": "99999",
    "city": "Aberdeen",
    "state": "WA",
    "jurisdiction": "indeterminate",
    "lec": "Verizon",
    "linetype": "landline"
  },
  "cnam": {
    "caller_id": "John Smith"
  }
}
```

**SDK Code**

```python
import requests

url = "https://{your_space_name}.signalwire.com/api/relay/rest/lookup/phone_number/e164_number"

response = requests.get(url, auth=("<project_id>", "<api_token>"))

print(response.json())
```

```javascript
const url = 'https://{your_space_name}.signalwire.com/api/relay/rest/lookup/phone_number/e164_number';
const credentials = btoa("<project_id>:<api_token>");

const options = {method: 'GET', headers: {Authorization: `Basic ${credentials}`}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{your_space_name}.signalwire.com/api/relay/rest/lookup/phone_number/e164_number"

	req, _ := http.NewRequest("GET", url, nil)

	req.SetBasicAuth("<project_id>", "<api_token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://{your_space_name}.signalwire.com/api/relay/rest/lookup/phone_number/e164_number")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request.basic_auth("<project_id>", "<api_token>")

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://{your_space_name}.signalwire.com/api/relay/rest/lookup/phone_number/e164_number")
  .basicAuth("<project_id>", "<api_token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://{your_space_name}.signalwire.com/api/relay/rest/lookup/phone_number/e164_number', [
  'headers' => [
  ],
    'auth' => ['<project_id>', '<api_token>'],
]);

echo $response->getBody();
```

```csharp
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://{your_space_name}.signalwire.com/api/relay/rest/lookup/phone_number/e164_number");
client.Authenticator = new HttpBasicAuthenticator("<project_id>", "<api_token>");
var request = new RestRequest(Method.GET);

IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let credentials = Data("<project_id>:<api_token>".utf8).base64EncodedString()

let headers = ["Authorization": "Basic \(credentials)"]

let request = NSMutableURLRequest(url: NSURL(string: "https://{your_space_name}.signalwire.com/api/relay/rest/lookup/phone_number/e164_number")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```