# PHONE-CHECK.APP Public API

> Phone number validation and intelligence API for production applications: format and line-type validation, carrier lookup, NPA-NXX enrichment, and disposable-number detection.

The API is served at `https://api.phone-check.app` (the same API is also reachable same-origin at `https://phone-check.app/api`). All endpoints authenticate with an `x-api-key` header and are billed per call.

## Start here

- Interactive API reference (with one-click MCP install buttons): https://phone-check.app/open-api
- MCP integration guide for AI agents: https://phone-check.app/guides/mcp-server
- OpenAPI document (machine-readable, this is the contract): https://phone-check.app/json/open-api.json
- Pricing and credit packs: https://phone-check.app/pricing
- Live demo in the browser: https://phone-check.app/try
- Guides: https://phone-check.app/guides
- Technical articles: https://phone-check.app/blog

## MCP server for AI agents

- Endpoint: https://api.phone-check.app/mcp
- Transport: Streamable HTTP — POST JSON-RPC 2.0, header `Accept: application/json, text/event-stream`
- Auth: `x-api-key` header with a product API key (host-scoped; cross-product keys are rejected with A1003)
- Demo access: key `demo-key` with a valid TOTP in `x-ct` (rate-limited, evaluation only)
- Billing: 1 credit per tool call; `account_whoami` is free; HTTP 402 means out of credits (top up at https://phone-check.app/pricing)
- Tools: - account_whoami (free identity probe)
- phone_validate
- phone_lookup_npa_nxx (US/CA NPA-NXX enrichment)
- Discovery: https://phone-check.app/.well-known/mcp/server-card.json · this llms.txt · the Scalar MCP panel on /open-api
- Supported clients: Claude Code, Claude (claude.ai + Desktop), Codex (CLI, IDE extension, ChatGPT desktop app), Cursor, VS Code (Copilot), Windsurf, Cline, Continue, Zed, Gemini CLI, and any client that speaks Streamable HTTP.
- The server returns agent instructions in the MCP initialize result.

## Authentication and errors

- `x-api-key` header (or `x-api-key` query parameter) — create keys at https://phone-check.app/account/api-keys. Keys are scoped to this product host.
- `x-jwt-token` header — session alternative; when both are present the API key wins.
- Error envelope: `{ "error": "CODE", "message": "...", "issues": [...] }`. Auth codes: A1001 missing credential, A1002 malformed key, A1003 unknown/disabled key or cross-host key, A1004 invalid TOTP, A1006 unverified account, A1008 authentication required, A1009 admin required.
- Rate limits: guest limits are strict and per-IP; authenticated keys get plan-based limits (429 with Retry-After when exceeded).

## API endpoints

### Phone Lookup
- `GET /v1-get-phone-details` — Validate a phone number: Validate one phone number and return normalized number data, carrier hints, line type, location, timezone, and disposable-number signals when available.
- `GET /v1-get-phone-extra-details` — Get extended phone intelligence: Return expanded phone intelligence for workflows that need local and international formats, country details, carrier candidates, and line-type classification.

### Bulk Validation
- `POST /v1-upload-phone-json` — Start a bulk validation job: Upload JSON rows and identify the phone-number field. The API creates a validation job and returns the initial job counters.
- `POST /v1-list-upload-phone-json` — List bulk validation jobs: List the authenticated account's bulk phone validation jobs, optionally filtered by batch ID or job status.
- `POST /v1-download-phone-json` — Download bulk validation results: Fetch processed validation records and job counters for a completed or in-progress bulk phone validation batch.
- `POST /v1-resume-phone-json` — Resume a bulk validation job: Retry a stuck or failed bulk validation job by re-queueing pending records and resetting recoverable failed records.

### API Keys
- `POST /v1-create-api-key` — Create an API key: Create an API key for phone-check integrations. Use the returned key with single-number lookup endpoints.
- `POST /v1-list-api-keys` — List API keys: List API keys available to the authenticated phone-check account.
- `POST /v1-get-api-key-details` — Get API key details: Fetch the status, allowed services, and metadata for one API key.
- `POST /v1-update-api-key` — Update an API key: Rename an API key, update enabled services, or enable and disable the key.
- `POST /v1-delete-api-key` — Delete an API key: Delete an API key so it can no longer be used for phone lookup requests.

### Usage
- `GET /v1-get-api-usage` — View API usage: Return daily usage rows for phone-check requests in the selected date range.
- `GET /v1-download-api-usage` — Download API usage: Create a downloadable usage export for phone-check requests in the selected date range.

### Authentication
- `GET /v1-who-am-i` — Check authentication context: Return the account and request context currently associated with the bearer token.

## Workflows

- Signup screening — validate the phone number at registration with phone_validate; reject invalid or disposable numbers.
- SMS list cleaning — batch-validate lists through the bulk JSON upload endpoints before a campaign.
- Lead routing and scoring — use phone_lookup_npa_nxx carrier and line-type data to score and route leads.
- Fraud and VoIP review — disposable detection plus carrier data flag risky numbers for manual review.

## Notes for agents

- All lookups are read-only and cache-backed; pass `skipCache=true` only when freshness matters.
- The bulk JSON upload endpoints run asynchronously: upload, poll list status, then download results.
- Tool calls over MCP and REST calls cost the same credits and return the same data shapes.