Get Started with 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 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 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 for help.

Once you have an account, read about our server SDKs 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

import plivo

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

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

print(response)

​

Sample Response

​

Success

{
    "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

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