Number lookup

Single lookup

curl "https://api.anthonyoliva.com/v1/lookup/+13155550188" \
  -u "$AO_KEY_ID:$AO_KEY_SECRET"

{
  "phone_number": "+13155550188",
  "national_format": "(315) 555-0188",
  "valid": true,
  "line_type": "mobile",
  "carrier": {
    "name": "Verizon Wireless",
    "mcc": "311",
    "mnc": "480"
  },
  "ported": true,
  "country_code": "US",
  "looked_up_at": "2026-07-27T18:02:11Z"
}

Batch lookup

curl https://api.anthonyoliva.com/v1/lookup/batch \
  -u "$AO_KEY_ID:$AO_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "phone_numbers": ["+13155550188", "+16465550143", "+12125550119"] }'

Up to 10,000 numbers per request. Results are returned in the order submitted, with a null result and an error field for any number that could not be resolved. A partial failure does not fail the request.

Why it is worth running

Filter landlines before an SMS send. An SMS to a landline is billed and never arrives. On a list assembled from web forms, landlines are routinely a few percent of the total.

Catch invalid numbers. Typos in a signup flow cost a segment each and drag down your delivery rate, which is a signal carriers watch.

Detect reassignment. Disconnected numbers get reassigned to new subscribers. Messaging a reassigned number means messaging someone who never consented, which is direct TCPA exposure. A valid: false result or a carrier change on a number you have messaged before is worth acting on.

Route by line type. Send SMS to mobile, place a voice call to landline, and skip the numbers that cannot receive either.

Pricing and latency

$0.004 per lookup, billed per number including batch entries. Typical latency is under 300 ms for a single lookup.

Results are not cached across requests, because a stale carrier record defeats the purpose. If you look up the same number twice you are billed twice.

Rate limits

Single lookups follow the standard GET limit of 100 requests per second. Batch requests are limited to 10 per second regardless of size.