Phone Lookup API

What you get

• The same report the website produces — API callers are not served a reduced tier.
• Telecom facts with near-universal coverage: validity, region, carrier, line type.
• The public-footprint layer where it exists: linked accounts, usernames, prior reports.
• A flat price per call: one credit, however much the number turns out to be known.
• No query logging: we keep the endpoint, the status and the time, never the number or the report.

How does it work?

1. 01Create an account and a key

   Sign up at /developers/register/ with an email and a password — no card is needed for a key. In the dashboard, open the API keys tab and create one. The secret appears exactly once, because only its SHA-256 hash is stored; a lost key is revoked and replaced rather than recovered.

   Illustration

2. 02Buy credits

   On the Billing tab, choose a pack — 3 credits for $3.95, 7 for $6.95, or any amount from 3 to 50 — and pay through Stripe. Credits appear on your balance as soon as Stripe confirms and never expire. One credit is one lookup, whether the number comes back rich or nearly empty.

   Illustration

3. 03POST a number

   Send JSON with a `phone` field and your key as a bearer token. Use international format — the country code decides how the rest of the digits are parsed, and a number without one is ambiguous. The API normalises spacing and punctuation for you.

   Illustration

4. 04Read the report

   The response carries the report as structured JSON — the telecom block first, then whatever public-footprint data exists for that number. Most lookups return in a few seconds. An empty identity layer is a real answer, not an error: plenty of numbers simply have no public footprint.

   Illustration

Code to copy

The same call in three places. A Postman collection is available too, with both endpoints and saved example responses.

curl -X POST https://catchnumber.com/api/v1/lookup \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+14155550134"}'

const response = await fetch("https://catchnumber.com/api/v1/lookup", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone: "+14155550134" }),
});

const { success, data, credits_remaining } = await response.json();
if (!success) throw new Error("lookup failed");
console.log(data, credits_remaining, "credits left");

import os, requests

response = requests.post(
    "https://catchnumber.com/api/v1/lookup",
    headers={"Authorization": f"Bearer {os.environ['CN_API_KEY']}"},
    json={"phone": "+14155550134"},
    timeout=90,
)

payload = response.json()
if payload["success"]:
    print(payload["data"])

A failed lookup never costs a credit. If the provider errors or the number is rejected, the deduction is reversed before the error reaches you — a 4xx or 5xx leaves your balance untouched.

Limits and guarantees

What people build with it

Questions

How much does the phone lookup API cost?

One credit per lookup. Credits are $3.95 for three, $6.95 for seven, or any amount from 3 to 50 priced as on the pricing page. No subscription, no monthly minimum, and credits do not expire.

Will the API always return the owner's name?

No, and any API that promises it is overselling. Carrier, line type, region and validity come back reliably; owner records and linked accounts exist for some numbers and not others, and coverage is thinnest for prepaid mobiles. An empty identity layer is a real answer rather than a failure.

What happens if a lookup fails?

The credit is refunded automatically. The deduction happens immediately before the provider call, and every failure after that point reverses it before the error is returned.

Can it tell me where a phone is right now?

No. The region in a report is where the number was issued or is routed, not where the handset is. Real-time location from a number alone is not legally available to the public, whatever other services advertise.

Does it work for numbers outside the US?

Yes, with honest caveats. Validity, country and line type are broadly available; carrier accuracy depends on how well a country publishes porting data, and the public-footprint layer varies by market. Always send the country code.

Do you store the numbers I look up?

No. The number goes to the provider and the report comes back in the response; neither is written to disk. Per call we record the endpoint, the status code, the key and the time — what billing and rate limiting need, and nothing else.

Can I use it for employment or tenant screening?

No. CatchNumber is not a consumer reporting agency, and results must not drive decisions about employment, credit, housing, tenancy or insurance. It is built for fraud and safety checks.

What do I do if a key leaks?

Revoke it in the dashboard — it stops working immediately — then create a replacement. Up to ten keys can be active at once, so rotating in production need not cause downtime.