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

# Get Started with Lookup API

> Validate and format phone numbers using the Plivo Lookup API.

Lookup API helps you format phone numbers and retrieve additional information before sending SMS and MMS messages or making voice calls. Unformatted numbers may be invalid, which can cause calls and messages to fail. With Lookup, you can identify local number formats and reduce the likelihood of undelivered messages. Here’s how to get started with the Lookup API.

## Sign up for a Plivo account

If you’re not already a Plivo customer, you can [sign up for a free trial account](https://cx.plivo.com/signup) to experiment with and learn about our services. Be sure to sign up with your work email address and not one from a generic email provider. Each trial account comes with free credits. You can [add more credits and buy a phone number](https://cx.plivo.com/phone-numbers) to test the full range of our voice and SMS service features.

If you have any issues creating a Plivo account, please reach out to our [support team](https://support.plivo.com/hc/en-us/) for help.

Once you have an account, read about our [server SDKs](/sdk/server/php-sdk/) and install the one for the programming language you want to use.

## Looking up a number

Lookup API enables you to identify phone number types (mobile, fixed, VoIP, and toll-free) and the service provider of the phone number, including ported numbers in the US and Canada.

## Code

<CodeGroup>
  ```py Python theme={null}
  import plivo

  client = plivo.RestClient('<auth_id>','<auth_token>')

  #Number lookup API
  response = client.lookup.get("<your_number>")

  print(response)
  ```

  ```ruby Ruby theme={null}
  require 'rubygems'
  require 'plivo'

  include Plivo
  include Plivo::Exceptions

  api = RestClient.new("<auth_id>","<auth_token>")

  # Numberlookup API
  begin
  response = api.lookup.get('your_number')
  puts response
  rescue PlivoRESTError => e
      puts 'Exception: ' + e.message
  end
  ```

  ```js Node.js theme={null}
  let plivo = require('plivo');

  let client = new plivo.Client('<auth_id>', '<auth_token>');

  // Numberlookup
  client.lookup.get("<your_number>")
  .then(function(response) {
      console.log(response);
  }).catch(function(error) {
      console.log(error);
  });
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';
  use Plivo\RestClient;

  $client = new RestClient("<auth_id>", "<auth_token>");

  $client->client->setTimeout(40);

  // Numberlookup API Product
  try { 
  $response = $client->lookup->get("<your_number>");
  print_r($response);
  }
  catch (PlivoRestException $ex) {
      print_r(ex);
  }
  ```

  ```java Java theme={null}
  package test;
  import java.io.IOException;
  import com.plivo.api.exceptions.PlivoRestException;
  public class Test {
  	public static void main(String[] args) {
  		Plivo.init("<auth_id>", "<auth_token>");
          //Number Lookup API
  		try {
  				System.out.println(com.plivo.api.models.lookup.Number
  			        .getter("<your_number>")
  			        .get());
  		} catch (IOException e) {
  				e.printStackTrace();
  		} catch (PlivoRestException e) {
  				e.printStackTrace();
  		}
  	}
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"

  	plivo "github.com/plivo/plivo-go/v7"
  )

  func main() {

  	client, err := plivo.NewClient("<auth_id>", "<auth_token>",
  		&plivo.ClientOptions{})
  	if err != nil {
  		fmt.Print("Error", err.Error())
  		return
  	}

  	// Numberlookup
  	response, err := client.Lookup.Get("<your_number>",
  		plivo.LookupParams{})
  	if err != nil {
  		fmt.Print("Error", err.Error())
  		return
  	}
  	fmt.Printf("Response: %#v\n", response)
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Collections.Generic;
  using Plivo;
  using Plivo.Exception;

  namespace test_apps
  {
      class Program
      {
          static void Main(string[] args)
          {
              var api = new PlivoApi("<auth_id>","<auth_token>");

              // Number Look Up API
              try
              {
                  var response = api.Lookup.Get("<your_number>");
                  Console.WriteLine(response);
              }
              catch (PlivoRestException e)
              {
                  Console.WriteLine("Exception: " + e.Message);
              }
          }
      }
  }
  ```

  ```sh Curl theme={null}
  curl -i --user auth_id:auth_token \
  https://lookup.plivo.com/v1/Number/{PhoneNumber}?type=carrier
  ```
</CodeGroup>

## Sample Response

### Success

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

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