# Reverse Phone Lookup API (reverse-phone-lookup-api) — PayloadAPI LLM & Agent Reference

> Perform a reverse phone lookup to retrieve the registered name associated with a phone number. Validates the number, checks priority regional databases (IN, IL), and queries global CNAM networks.

## Quick Facts
- **Catalog Page**: https://payloadapi.com/apis/reverse-phone-lookup-api
- **LLM Context URL**: https://payloadapi.com/apis/reverse-phone-lookup-api/llms.txt
- **Gateway Origin**: `https://gateway.payloadapi.com`
- **Trust Score**: 75/100
- **Published Versions**: `v1` (REST)
- **30-Day Availability**: 100%
- **P95 Latency**: 5694 ms

## Authentication
All requests route through the PayloadAPI Edge Gateway and authenticate with a buyer application key in the `Authorization` header. Never hardcode keys; export `$PAYLOADAPI_KEY` in your environment:

```bash
export PAYLOADAPI_KEY="payload_live_<app_public_id>.<secret>"
```

Required request header:
```http
Authorization: Bearer $PAYLOADAPI_KEY
```

## Edge REST-to-MCP Bridge (Model Context Protocol)
Every REST version of `reverse-phone-lookup-api` is automatically exposed as a JSON-RPC 2.0 MCP server at the edge. Discovery methods (`initialize`, `notifications/initialized`, `ping`, `tools/list`) are **quota-free**; `tools/call` executions are metered against your active plan.

- **MCP Server Endpoint**: `POST https://gateway.payloadapi.com/reverse-phone-lookup-api/v1/mcp`

### One-Click MCP Configuration (`.cursor/mcp.json` / `claude_desktop_config.json` / Antigravity)
```json
{
  "mcpServers": {
    "payloadapi-reverse-phone-lookup-api": {
      "url": "https://gateway.payloadapi.com/reverse-phone-lookup-api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PAYLOADAPI_KEY}"
      }
    }
  }
}
```

### Synthesized MCP Tools
- `get_calleridvalidation` (`GET /calleridvalidation`, `v1`, required: phone_number) — Validate phone number and lookup caller ID

## Live Plans & Quota Terms
- Free (Free: 50 requests / month)

## Endpoints

### Version `v1` (REST)

- **Gateway Base Path**: `https://gateway.payloadapi.com/reverse-phone-lookup-api/v1`
- **MCP Bridge Endpoint**: `POST https://gateway.payloadapi.com/reverse-phone-lookup-api/v1/mcp`

#### `GET /calleridvalidation`
**Validate phone number and lookup caller ID**
Validates phone number and performs reverse caller ID lookup against regional and global CNAM databases.
- **Gateway URL**: `https://gateway.payloadapi.com/reverse-phone-lookup-api/v1/calleridvalidation`
- **Synthesized MCP Tool**: `get_calleridvalidation`
- **Parameters**:
  - `phone_number` (query, string, required) — Phone number in international E.164 format (e.g. +14155552671)

```bash
curl --request GET 'https://gateway.payloadapi.com/reverse-phone-lookup-api/v1/calleridvalidation?phone_number=%2B14155552671' --header "Authorization: Bearer $PAYLOADAPI_KEY"
```