# 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 phone number 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 API key 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 API key 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 API key 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 languages. 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 `/v1/validate` 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/)
- [Dive into the phone number validation endpoint](/validate)
- [Learn about the request status codes and validation errors](/status-codes)
- [Test your integration with sandbox API keys](/testing)

---

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 — you can find the limits of each plan on the [pricing page](https://numlookupapi.com/#pricing). 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
```

In addition, successful lookup responses (e.g. from [`/v1/validate`](/validate)) tell you what the request cost and how long it took to process:

- **X-Cost** (integer):
The number of requests this call counted against your quota. Requests made with a [sandbox API key](/testing) return `X-Cost: 0`. Responses from [`/v1/status`](/status) never count against your quota and simply carry no `X-Cost` header.

- **X-Execution-Time** (number):
The server-side processing time of the request in milliseconds.

---

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

- **account_id** (integer):
The id of your numlookupapi account (team).

- **quotas** (object):
Contains information about your request quota, split into a `month` and a `grace` bucket.

- **quotas.month** (object):
Your monthly request quota: `total` (the quota included in your plan), `used` (requests consumed this month) and `remaining` (requests left this month, always `total - used`).

- **quotas.grace** (object):
Your grace quota with the same `total`, `used` and `remaining` fields. The grace quota is a temporary allowance we grant while there is an issue with your subscription payment, so your integration keeps working until the payment is completed. While a grace quota is active, requests count against it instead of your monthly quota. If no grace period is active, all values are `0`.

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

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

const client = new Numlookupapi('YOUR-API-KEY')
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": 228
        },
        "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 [numlookupapi support](mailto:support@numlookupapi.com).

---

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

- **200**:
A 200 status code indicates a successful response. Note that a well-formed but unrecognised phone number also returns a 200 — check the `valid` field of the response, see the [validation endpoint](/validate).

- **401**:
A 401 status code indicates that your request was not authenticated: the API key is missing or invalid. A missing key returns the message `No API key found in request` (error code `missing_api_key`); an invalid key returns `Invalid authentication credentials` (error code `invalid_api_key`) — see [Authentication](/authentication).

- **403**:
A 403 status code indicates that your request was refused: either the API key belongs to a different everapi product (error code `key_not_allowed_for_product`), or the request came from a referrer that is not on your API key's whitelist (error code `referrer_not_allowed`).

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

- **422**:
A validation error has occurred, please check the list of [validation errors](#validation-errors).

- **429**:
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).

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

---

## Validation Errors

- **invalid_number**:
The phone number is empty or could not be parsed. Provide the number either including its country prefix (e.g. `+14158586273`) or without the prefix together with the `country_code` parameter.

- **invalid_country_code**:
The selected country_code is invalid.
Should be an ISO 3166-1 alpha-2 country code (e.g. `US`), used to prepend the correct country prefix to 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` |

### Sandbox responses

Sandbox requests return dummy data instead of live lookup results. Every number apart from the test numbers above validates with `"valid": true` and Austrian dummy data: `"country_name": "Austria"`, `"country_code": "AT"`, `"carrier": "Demo Operator"` and `"line_type": "mobile"`. Since sandbox requests do not count against your quota, their responses carry an `X-Cost: 0` header — see [Rate Limit & Quotas](/rate-limit).

---

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

- **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

### Invalid numbers

A well-formed but unrecognised number does not produce an error: the API returns HTTP `200` with `"valid": false`, empty strings for the formatting, country, location and carrier fields, and `"line_type": "N/A"`.

Always check the `valid` field of the response, not the HTTP status code. A `422` status is only returned for malformed input, e.g. an empty number (`invalid_number`) or an unknown `country_code` (`invalid_country_code`) — see [Request Status Codes](/status-codes).

```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"
}
```

```json {{title: 'Response for an unrecognised number'}}
{
    "valid": false,
    "number": "14158586273",
    "local_format": "",
    "international_format": "",
    "country_prefix": "",
    "country_code": "",
    "country_name": "",
    "location": "",
    "carrier": "",
    "line_type": "N/A"
}
```

---