NewConnect Claude, Gemini, ChatGPT, and other AI agents to API Ninjas via our MCP server →

Phone Lookup API

The Phone Lookup API returns line intelligence for a phone number — carrier, line type, VOIP status, and MCC/MNC — worldwide, sourced from free public data. For basic validation and formatting, see the Validate Phone API.

(4.3)

From 2,696 users

800+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average
P50
P75
P90
P95
304ms322ms381ms748ms1239ms

Didn't find what you were looking for? Suggest an improvement

/v1/phonelookup GET

https://api.api-ninjas.com/v1/phonelookup

Returns carrier, line type, and network metadata for a given phone number.

Parameters

  • number  required

    Phone number to look up. If country is not set, the country code prefix needs to be included.

  • country  optional

    2-letter ISO-3166 country code the phone number belongs to.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON object with the following fields or an error if the request is unsuccessful. Fields marked premium require a Business or higher subscription.

  • is_valid

    Whether the phone number is valid.

  • number

    The phone number in E.164 format.

  • country

    Full country name the number is registered to.

  • country_code

    The international country calling code (e.g. 1 for the US).

  • region_code

    2-letter ISO-3166 region code (e.g. US).

  • location

    Sub-national geographic description, when available.

  • line_type

    Line type such as mobile, landline, voip, or toll_free (North American numbers may report fixed_line_or_mobile).

  • carrier

    Carrier / operator name (original allocation, not corrected for number portability).

  • is_voip  premium

    Whether the number belongs to a VOIP provider.

  • mcc  premium

    Mobile Country Code of the operator, when known.

  • mnc  premium

    Mobile Network Code of the operator, when known.

  • is_disposable  premium

    Whether the number is a known disposable / receive-SMS number.

Sample Request Live Demo!

number
country

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

https://api.api-ninjas.com/v1/phonelookup?number=%2B12065550100

Headers

X-Api-KeyLog in or sign up to get your API Key

Sample Response

JSON
{
    is_valid:true,
    number:"+12065550100",
    country:"United States",
    country_code:1,
    region_code:"US",
    location:"Washington State",
    line_type:"fixed_line_or_mobile",
    carrier:"CenturyLink Communications, LLC",
    is_voip:false,
    mcc:null,
    mnc:null,
    is_disposable:false
}

Code Examples

1 2 curl -X GET "https://api.api-ninjas.com/v1/phonelookup?number=%2B12065550100" \ -H "X-Api-Key: YOUR_API_KEY"

If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.

Frequently Asked Questions

  • Yes, but you must have a premium subscription. Commercial use of the Phone Lookup API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.
  • Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.
  • Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.
  • The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.
  • For a given number, it returns is_valid, the E.164 number, country, country_code, region_code, location, line_type, and carrier. Premium (Business+) responses also include is_voip, mcc, mnc, and is_disposable. If you only need validity and formatting, see the Validate Phone API.
  • Validity, country, location, line_type, and carrier are available on all plans. The is_voip, mcc, mnc, and is_disposable fields require a Business or higher subscription. Carrier data reflects the original number allocation and is not corrected for number portability.
  • Line type and original carrier are available worldwide from the underlying numbering plans, with enhanced carrier and VOIP data for the United States and selected European markets. All data comes from free, public numbering sources.