# numberRank

https://numberrank.dev

Check whether a phone number reads as VoIP or a real carrier line, and see it
head to head against a real carrier number. Free, no auth, no API key. US numbers first.
Source of truth: Twilio Lookup v2 line_type_intelligence.

## Endpoint

GET /api/check?number=<phone>[&format=text][&ref=<your-agent-name>]

- number: required. Raw US number (10 digits, or 11 starting with 1) or any E.164
  number starting with + and its country code. Example: +15551234567. Numbers
  outside the US work when the country code is included; the score rubric is the
  same everywhere.
- format=text: optional. Returns one or two plain lines you can read to the user
  as-is. Also honoured when Accept: text/plain is sent.
- ref: optional. Name your agent or app so we can see where checks come from.

CORS is open (Access-Control-Allow-Origin: *). Rate limit is about 20 checks per
minute per IP.

## Response (default JSON, 200)

{
  "number": "+19894496601",
  "display": "+1 (989) 449-6601",
  "valid": true,
  "type": "nonFixedVoip",
  "carrier": "Twilio - SMS/MMS-SVR",
  "mcc": "311",
  "mnc": "950",
  "score": 15,
  "grade": "F",
  "verdict": { "pass": false, "label": "VoIP", "note": "VoIP numbers are rejected by most OTP and fraud systems." },
  "provider": "twilio_line_type_intelligence",
  "gather": { "type": "mobile", "carrier": "Onvoy Spectrum", "mcc": "312", "mnc": "850",
              "score": 95, "grade": "A",
              "verdict": { "pass": true, "label": "Real carrier (mobile)", "note": "..." } }
}

type is one of: mobile, landline, nonFixedVoip, fixedVoip, voip, tollFree, or null.
tollFree is reported but not scored (score and grade are null).
verdict.pass is true only for mobile.

score (integer 0-100 or null) and grade (A to F or null) are set by line type alone:
  mobile 95, fixedVoip 45, nonFixedVoip 15, voip 15, landline 10, unknown null.
  Grade bands: A 90-100, B 70-89, C 50-69, D 30-49, F 0-29.
The score reflects line type, it is not a measured delivery rate. A real carrier
number tops out at 95, not 100, because even a real number can be blocked if its
range has a bad reputation. When type is null, score and grade are null and the
verdict says the line could not be classified.

## Response (format=text, 200)

+1 (989) 449-6601 is a VoIP number (nonFixedVoip, Twilio - SMS/MMS-SVR, Twilio, score 15, grade F). It will fail OTP on most services.
A Gather number reads as a real mobile line (mobile, Onvoy Spectrum, score 95, grade A) on the same lookup.

## Directory

GET /api/directory  JSON: { asOf, method, count, companies: [ { name, category, type,
carrier, score, grade, masked, source, unscored } ] }
A benchmark of companies graded by the line type of the number they publish
publicly. Numbers are masked. Human page: https://numberrank.dev/directory

## Errors

400 { "error": "invalid_number", "message": "..." }
429 { "error": "rate_limited", "message": "..." }
502 { "error": "lookup_failed", "message": "..." }

## Example

curl "https://numberrank.dev/api/check?number=+15551234567&format=text&ref=my-agent"

## Honest framing

Line type providers disagree with each other on the same number. This tool
reports what Twilio Lookup returns and nothing else. A Gather number reads as a
real mobile carrier line on Twilio Lookup. That is a claim about line type, not a
guarantee that every OTP everywhere will pass.

numberRank is powered by Gather. Need a number that passes: https://www.gatherat.ai?ref=numberrank