# numlookupapi documentation

> numlookupapi validates phone numbers and returns their formatting, country, location, carrier and line type over a simple JSON REST API.

Authenticate every request with your API key via the `apikey` query parameter or request header. Base URL: https://api.numlookupapi.com

OpenAPI specification: https://numlookupapi.com/docs/openapi.yaml

---

Source: https://numlookupapi.com/docs

# numlookupapi.com API Documentation

Use the numlookupapi.com API to retrieve information about any email address and seamlessly integrate it into your product using one of our many SDKs or other pre-built integrations.

Building with an AI assistant? The full API is available as a machine-readable [OpenAPI 3.1 specification](https://numlookupapi.com/docs/openapi.yaml), and the documentation is published as [llms.txt](https://numlookupapi.com/docs/llms.txt) / [llms-full.txt](https://numlookupapi.com/docs/llms-full.txt). There is also a hosted [MCP server](https://numlookupapi.com/docs/mcp) at `https://api.numlookupapi.com/mcp` that AI agents can connect to directly.

## Getting started

To get started, you have to register an API key [here](https://app.numlookupapi.com/register). Then, follow our quickstart guide or continue reading our documentation and integrate numlookupapi, using our HTTP API and dedicated client SDKs. Ultimately, [upgrade your plan](https://app.numlookupapi.com/subscription) to access all data & endpoints.

---

Source: https://numlookupapi.com/docs/authentication

# Authentication

You'll need to authenticate your requests to access any of the endpoints in the numlookupapi.com API. In this guide, we'll look at how authentication works. numlookupapi offers two ways to authenticate your API requests: API key as `GET` parameter, or via request header.

**MULTIPLE API KEYS**
While our free plan only allows one API key at a time, our [paid plans](https://app.numlookupapi.com/subscription) offer multiple API keys.
By using separate keys for different use cases you can track individual usage and make key rotations affect only certain parts of your application.

## GET query parameter

You can pass your API key along with every request by adding it as a query parameter `apikey`

**WARNING**
This method could expose your API key in access logs and such. Sending the API key via a header parameter as specified below circumvents this problem.

```bash {{ title: 'Example request with authentication via get request' }}
curl "https://api.numlookupapi.com/v1/status?apikey=YOUR-API-KEY"
```

Please don't commit your numlookupapi password to GitHub!

## HTTP Header

The recommended way to authenticate with the numlookupapi.com API through a HTTP request header:

```bash {{ title: 'Example request with authentication via header' }}
curl "https://api.numlookupapi.com/v1/status" \
  -H "apikey: YOUR-API-KEY"
```

Always keep your token safe and reset it if you suspect it has been compromised.

## Using an SDK

If you use one of our official SDKs, you won't have to worry about any of the above — fetch your access token from the [numlookupapi dashboard](https://app.numlookupapi.com/dashboard) and the client library will take care of the rest. All the client libraries use header authentication behind the scenes.

---

Source: https://numlookupapi.com/docs/mcp

'Connect AI agents to the numlookupapi API through our hosted MCP (Model Context Protocol) server.'

# MCP Server

numlookupapi ships a hosted [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so AI agents and assistants can call the API as native tools — no SDK or glue code required.

```
https://api.numlookupapi.com/mcp
```

The endpoint speaks the streamable HTTP transport. Listing the available tools works without authentication; executing a tool requires your API key, sent as the `apikey` header. You can [get a free API key here](https://app.numlookupapi.com/register).

## Connect

Using Claude Code:

```bash
claude mcp add --transport http numlookupapi https://api.numlookupapi.com/mcp --header "apikey: YOUR_API_KEY"
```

Or add the server to any MCP-capable client (Claude Desktop, Cursor, VS Code, ...):

```json
{
  "mcpServers": {
    "numlookupapi": {
      "url": "https://api.numlookupapi.com/mcp",
      "headers": { "apikey": "YOUR_API_KEY" }
    }
  }
}
```

## Available tools

The tools are generated from the same [OpenAPI specification](https://numlookupapi.com/docs/openapi.yaml) that describes the REST API, so they always match the documented endpoints, parameters and responses.

| Tool | Endpoint | Description |
|---|---|---|
| `validateNumber` | `GET /v1/validate/{number}` | Validate a phone number |
| `getStatus` | `GET /v1/status` | Account quota status |

## Quotas and errors

Tool calls are metered exactly like REST requests: they consume your plan quota and return the same status codes and error responses (`401`, `422`, `429`, ...). If a call fails, the tool result contains the API's error message including hints on how to proceed.

---

Source: https://numlookupapi.com/docs/quickstart

# Quickstart

This guide will get you all set up and ready to use the numlookupapi.com API. We'll cover how to get started using one of our API clients and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.

Before you can make requests to the numlookupapi.com API, you will need to grab your
API key from your dashboard. You find it under [App » Dashboard](https://app.numlookupapi.com/dashboard).

## Choose your client

Before making your first API request, you need to pick which API client you will use. In addition to cURL HTTP requests, numlookupapi offers [clients](/sdks) for JavaScript, Python, PHP and many more programming langauges. In the following example, you can see how to install each client.

```bash {{ title: 'cURL' }}
# cURL is most likely already installed on your machine
curl --version
```

```bash {{ language: 'js' }}
# Install the numlookupapi JavaScript SDK
npm install @everapi/numlookupapi-js --save
```

```bash {{ language: 'python' }}
# Install the numlookupapi Python SDK
pip install numlookupapi
```

```bash {{ language: 'php' }}
# Install the numlookupapi PHP SDK
composer require everapi/numlookupapi-php
```

## Making your first API request

After picking your preferred client, you are ready to make your first call to the numlookupapi.com API. Below, you can see how to send a
`GET` request to the `/info` endpoint to get the latest information about a telephone number.

```bash {{ title: 'cURL' }}
curl -G https://api.numlookupapi.com/v1/validate/+14158586273 \
    -H "apikey: YOUR-API-KEY"
```

```js
import Numlookupapi from '@everapi/numlookupapi-js';

const client = new Numlookupapi('YOUR-API-KEY')
client.validate('+14158586273').then(response => {
console.log(response);
});
```

```python
import numlookupapi

client = numlookupapi.Client('YOUR-API-KEY')
result = client.validate('+14158586273')
# Or use a country_code
# result = client.validate('4158586273', country_code='US')
print(result)
```

```php
$numlookupapi = new \Numlookupapi\NumlookupapiClient('YOUR-API-KEY');

var_dump($numlookupapi->validate('+14158586273'));
```

## What's next?

Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the numlookupapi.com API:

- [Grab your API key from the numlookupapi dashboard](https://app.numlookupapi.com/)

---

Source: https://numlookupapi.com/docs/rate-limit

# Rate Limit & Quotas

You can use a certain number of requests per month, defined by your plan.

Once you go over this quota, the API returns a `429` HTTP status code, and you either need to upgrade your plan or wait until the end of the month. We enforce a minute rate limit for specific plans. If you exceed this, the API returns a `429` HTTP status code. You then have to wait until the end of the minute to make more requests. Not every request counts towards your monthly request volume.

Not every request counts
Only successful calls count against your quota. Any error on our side or validation errors (e.g., wrong parameter) will NOT count against your quota or rate limit.

## Response Headers

We attach specific headers to tell you your current monthly/minute quota and how much you have remaining in the period.

```json lines
X-RateLimit-Limit-Quota-Minute: 10
X-RateLimit-Limit-Quota-Month: 300

X-RateLimit-Remaining-Quota-Minute: 5
X-RateLimit-Remaining-Quota-Month: 199
```

---

Source: https://numlookupapi.com/docs/sdks

# SDKs

The recommended way to interact with the numlookupapi.com API is by using one of our official SDKs. Today, numlookupapi offers fine-tuned JavaScript, Ruby, PHP and Python libraries to make your life easier and give you the best experience when consuming the API.

---

Source: https://numlookupapi.com/docs/status

# Status Endpoint

The status endpoint returns information about your current quota.

Requests to this endpoint do not count against your quota or rate limit.

---

## Check API Status

This status endpoint returns information about your current quota.

### Response Properties

- **quotas** (object):
Contains information about your request quota.

```bash {{title: 'cURL'}}
curl -G https://api.numlookupapi.com/v1/status \
    -H "apikey: YOUR-API-KEY"
```

```js
import numlookupapi from '@everapi/numlookupapi-js'

let status = await client.status();
console.log(status)
```

```python
import numlookupapi

client = numlookupapi.Client('YOUR-API-KEY')
result = client.status()
print(result)
```

```php
$client = new \Numlookupapi\NumlookupapiClient('YOUR-API-KEY');
$client->status();
```

```json {{title: 'Response'}}
{
    "account_id": 313373133731337,
    "quotas": {
        "month": {
            "total": 300,
            "used": 72,
            "remaining": 229
        },
        "grace": {
            "total": 0,
            "used": 0,
            "remaining": 0
        }
    }
}
```

---

Source: https://numlookupapi.com/docs/status-codes

# Request Status Codes

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). A successful request will be returned with status code `200`.

Before reaching out to support with an error, please be aware that 99% of all
reported errors are, in fact, user errors. Therefore, please carefully check
your code before contacting Protocol support.

---

## Status codes

Here is a list of the different categories of status codes returned by the numlookupapi.com API. Use these to understand if a request was successful.

A 200 status code indicates a successful response.

A 403 status code indicates that you are not allowed to use this endpoint, [please upgrade your plan](https://app.numlookupapi.com/subscription).

A 404 status code indicates that a requested endpoint does not exist.

A validation error has occured.

A 429 status code indicates that you have hit your rate limit or your monthly limit. For more requests [please upgrade your plan](https://app.numlookupapi.com/subscription).

A 500 status code indicates a internal server error - let us know: support@numlookupapi.com

---

## Validation Errors

The selected country_code is invalid
Should be an ISO Alpha 2 Language Code for localising the phone number

---

Source: https://numlookupapi.com/docs/testing

# Testing

Available in plans >= medium

This page includes all needed information to make sure your test environment works before deploying to production.

### Sandbox API Keys
An API request sent with a sandbox api key is automatically identified as a request in sandbox mode. All request with sandbox keys will respond with dummy data.

Requests done with sandbox keys do not count against your quota.

Please note that the requests are still shown in the graph on the dashboard. You can select only your live key if you want to filter them out.

### Test phone numbers

| Phone Number | Response |
| ----------- | ----------- |
| `+4312121212121`  `004312121212121`  `12121212121` + `country_code=AT` | `"valid": false` |
| all other numbers | `"valid": true` |

---

Source: https://numlookupapi.com/docs/validate

# Phone Number Validation Endpoint

On this page, we’ll dive into the phone number validation endpoint you can use to validate any given phone number and retrieve its carrier and location information.

---

## Validate Phone Number

This phone validation endpoint provides information about carrier & location information.

### Required attributes

- **phone_number** (string, path parameter):
The phone number you want to query (Either: including the country prefix, or without and you specify the country_code).

### Optional attributes

- **country_code** (string):
An ISO Alpha 2 Country Code for the phone number (e.g. US). If you specify this parameter you do not need to prepend the country prefix

### Possible `line_type` values
- landline
- mobile
- satellite
- paging
- special_services
- premium_rate
- toll_free
- N/A

```bash {{title: 'cURL'}}
curl -G https://api.numlookupapi.com/v1/validate/+14158586273 \
    -H "apikey: YOUR-API-KEY"
```

```js
import Numlookupapi from '@everapi/numlookupapi-js';

const client = new Numlookupapi('YOUR-API-KEY')
client.validate('+14158586273').then(response => {
    console.log(response);
});
```

```python
import numlookupapi

client = numlookupapi.Client('YOUR-API-KEY')
result = client.validate('+14158586273')
print(result)

```

```php
$numlookupapi = new \Numlookupapi\NumlookupapiClient('YOUR-API-KEY');

var_dump($numlookupapi->validate('+14158586273');
```

```json {{title: 'Full Response'}}
{
    "valid": true,
    "number": "14158586273",
    "local_format": "4158586273",
    "international_format": "+14158586273",
    "country_prefix": "+1",
    "country_code": "US",
    "country_name": "United States of America",
    "location": "Novato",
    "carrier": "AT&T Mobility LLC",
    "line_type": "mobile"
}
```

---