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. For basic validation and formatting, see the Validate Phone API.

Online
(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

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. The leading + is optional. If country is not set, include the country code (e.g. 13102000100 or +13102000100).

  • 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

The /v1/phonelookup endpoint returns a JSON object with the following fields, or an error if the request is unsuccessful. Fields marked Business tier and above 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.

  • line_type  Business tier and above

    Line type such as mobile, landline, voip, toll_free or fixed_line_or_mobile.

  • carrier  Business tier and above

    Carrier / operator name.

  • is_voip  Business tier and above

    Whether the number belongs to a VOIP provider.

  • mcc  Business tier and above

    Mobile Country Code of the operator.

  • mnc  Business tier and above

    Mobile Network Code of the operator.

  • is_disposable  Business tier and above

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

Live Demo

Live demo · no API key required
Query parameters
number
country

Get a free API key to get started — no credit card required.

Headers
X-Api-KeyLog in or sign up to get your API key
GET
https://api.api-ninjas.com/v1/phonelookup?number=%2B13102000100
Sample response
{
"is_valid": true,
"number": "+13102000100",
"country": "United States",
"country_code": 1,
"region_code": "US",
"location": "California",
"line_type": "fixed_line_or_mobile",
"carrier": "AT&T",
"is_voip": false,
"mcc": "310",
"mnc": "280",
"is_disposable": false
}

Code Examples

curl -X GET "https://api.api-ninjas.com/v1/phonelookup?number=%2B13102000100" \ -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, all plans return is_valid, the E.164 number, country, country_code, region_code, and location. Premium (Business+) responses add carrier, line_type, is_voip, mcc, mnc, and is_disposable. If you only need validity and formatting, see the Validate Phone API.
  • Validity, country, region, and location are available on all plans. The carrier, line_type, is_voip, mcc, mnc, and is_disposable fields require a Business or higher subscription.
  • Line type and carrier are available worldwide, with enhanced carrier and VOIP data for the United States.

Explore API integration use cases for recommended APIs and workflow examples.