# numbers.online

> A phone-number trust & intelligence API. Given a number in E.164, it returns a caller name
> (CNAM) where available and a supplementary, low-confidence spam-risk signal, plus
> compliance-aid checks (do-not-call scrub, DNC / reassigned status) and signed receipts.
> It is built for softphones, PBXs, SBCs, AI voice agents, chatbots, and CRMs.

## What it is (and is not)

- Every risk read is a **supplementary, low-confidence signal** — never an assertion that a call
  is "safe", "spam", lawful, or unlawful. A missing name means "unknown", not a negative signal.
- On any live-call path the API **fails open**: a slow or failing lookup returns a neutral/empty
  result and must never delay or drop a call.
- The integrating operator/agent keeps **every** routing, labeling, blocking, and dialing
  decision and remains responsible for compliance. Do-not-call results are a compliance aid, not
  a legal determination; `NO_MATCH` is not a consent grant.

## Base URL & authentication

- Base URL: `https://numbers.online`
- Auth header (preferred): `Authorization: Bearer <API_KEY>`  — or `X-API-Key: <API_KEY>`.
- Query-param auth `?key=<API_KEY>` is accepted only on header-less endpoints:
  `/api/v1/cid/{number}`, `/api/v1/integrations/retell/inbound`,
  `/api/v1/integrations/vapi/tool`, `/api/v1/sbc/redirect`.
- Keys are self-service: sign up at `https://numbers.online/docs`. A key is shown exactly once
  and stored only as a SHA-256 hash. Free tier is rate-limited; standard tier is prepaid.

## Core endpoints

- `GET  /api/v1/lookup/{e164}` — JSON lookup. Fields: `valid`, `formatted`, `line_type`,
  `carrier`, `country`, `cnam`, `verstat`, `spam_score` (1-99, may be null), `confidence`,
  `cached`, `receipt_id`. Invalid input returns 200 with `valid:false`.
- `POST /api/v1/lookup/batch` — up to 100 numbers: `{ "numbers": ["+1...", ...] }`.
- `GET  /api/v1/cid/{number}` — plain-text caller name for PBX CNAM (or `UNAVAILABLE`). Optional
  `?spam_tag=Spam?&spam_threshold=80&country=US&key=<API_KEY>`.
- `POST /api/v1/inbound/lookup` — inbound-call intelligence. Body `{ "number", "context"?,
  "verstat"?, "attestation"? }`. Fields: `identity_type`, `display_label` (never a personal
  name), `risk_level`, `recommended_action`, `signals`, `receipt_id`, `response_signature`.
- `POST /api/v1/mcp` — Model Context Protocol server (JSON-RPC 2.0 over Streamable HTTP,
  protocol "shttp"). Tools: `phone_lookup`, `line_type`, `caller_risk`, `dnc_check`,
  `reassigned_check`. `tools/list` is public; `tools/call` needs a key.
- `POST /api/v1/integrations/retell/inbound` — Retell `call_inbound` webhook (always 200; injects
  dynamic variables). `POST /api/v1/integrations/vapi/tool` — Vapi custom-function tool.
- `POST /api/v1/precall/lookup` — outbound pre-call do-not-call scrub: `SUPPRESS` / `NO_MATCH` /
  `UNKNOWN` (`NO_MATCH` is not consent). `POST /api/v1/precall/enroll` — enrol your own verified
  number for call-provenance / spoofing defence.
- `POST /api/match` — privacy-preserving identity match: `{ "number", "name" }` →
  `{ "status": "match"|"no_match"|"not_verified", "kind", "verified" }`. The stored name is never
  returned.
- `POST /api/scrub` — list scrubbing, up to 1,000 numbers. `POST /api/parse` — free E.164 parse.

## Authoritative references

- OpenAPI 3 spec (source of truth for every field & response code): `https://numbers.online/api/spec`
- Copy-paste AI-agent integration prompts: `https://numbers.online/ai-agents`
- Drop-in artifacts & step-by-step guides: `https://numbers.online/integrations`
- API reference & key signup: `https://numbers.online/docs`
- Pricing & rate limits: `https://numbers.online/pricing`