API reference

Base URL https://telephonydata.net/api/v1. All responses are JSON with snake_case fields.

Authentication

Every request needs your API key from the dashboard, sent as a bearer token (or in an X-Api-Key header).

Authorization: Bearer td_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are shown in full only to you. Rotating a key revokes the old one immediately.

GET /lookup/zip/{zipCode}

Returns the city, state, WGS 84 coordinates, IANA time zone and the UTC offset in effect right now (DST-aware) for a 5-digit ZIP. ZIP+4 input is accepted.

curl -H "Authorization: Bearer $KEY" https://telephonydata.net/api/v1/lookup/zip/80202

{
  "zip_code": "80202",
  "city": "Denver",
  "state": "CO",
  "latitude": 39.749,
  "longitude": -104.995,
  "iana_timezone": "America/Denver",
  "utc_offset": "-06:00",
  "utc_offset_minutes": -360,
  "standard_utc_offset_minutes": -420,
  "observes_dst": true,
  "is_dst_now": true,
  "local_time": "2026-10-29T16:05:12-06:00",
  "zip_type": "GEOGRAPHIC",
  "inherited_from_zip": null,
  "data_version": 12
}

zip_type is NON_GEOGRAPHIC for P.O. Box and unique-organization ZIPs; their coordinates and zone are inherited from inherited_from_zip.

GET /lookup/phone/{phoneNumber}

Accepts any 10-digit NANP number with optional +1, spaces, dots, dashes or parentheses (URL-encode + as %2B). The number is resolved by its pooled thousands-block when one exists, otherwise by its central office code (NPA-NXX).

curl -H "Authorization: Bearer $KEY" https://telephonydata.net/api/v1/lookup/phone/3035550199

{
  "phone": { "e164": "+13035550199", "national": "(303) 555-0199", "npa": "303", "nxx": "555", "line_number": "0199" },
  "line_type": "LANDLINE",
  "carrier": { "name": "QWEST CORPORATION", "ocn": "9636" },
  "rate_center": "DENVER",
  "state": "CO",
  "source": "CENTRAL_OFFICE_CODE",
  "reputation_score": 100,
  "location": { "zip_code": "80202", "city": "Denver", "iana_timezone": "America/Denver", "utc_offset": "-06:00", ... },
  "compliance": {
    "calling_window": {
      "is_callable_now": true,
      "local_time": "2026-10-29T16:05:12-06:00",
      "window_start_today": "08:00",
      "window_end_today": "21:00",
      "next_window_opens": null,
      "is_federal_holiday": false,
      "governing_rule": "FEDERAL_TCPA",
      "citation": "47 CFR 64.1200(c)(1) (TCPA)"
    },
    "disclaimer": "Calling windows reflect federal TCPA hours and known stricter state solicitation statutes. Informational only; not legal advice."
  },
  "data_version": 12
}

line_type is one of WIRELESS, LANDLINE, VOIP or UNKNOWN and reflects the carrier holding the block. Numbers ported to another carrier are not tracked.

The calling window applies the stricter of the federal TCPA window (8:00–21:00 local) and state statutes we track (AL, CT, FL, KY, LA, MA, MD, MS, OK, RI, TX, UT, WA, WY), including Sunday and holiday prohibitions. When calls aren't permitted, next_window_opens gives the next local opening.

Errors & limits

Errors use RFC 7807 problem JSON with title and detail.

Successful responses include a Server-Timing: lookup;dur=… header with server-side lookup time in milliseconds. Free-tier responses include X-Free-Lookups-Remaining.

Metering

Only successful (2xx) lookups count. Free accounts get 1,000 lookups per calendar month (UTC). On the metered plan every successful lookup is billed at the per-lookup rate on your monthly invoice, and usage appears on your dashboard within a minute.

Bulk files

Prefer zero network calls? Purchase the master database from Pricing. Each release ships as a CSV package (three tables plus a README) and a SQL seed script with CREATE TABLE and batched INSERT statements, ready for PostgreSQL or MySQL.