Skip to main content
GET
/
lookup
Lookup a phone number
curl --request GET \
  --url https://api.callheater.com/lookup \
  --header 'X-API-Key: <api-key>'
{
  "meta": {
    "timestamp": "2026-05-03T00:00:00Z",
    "elapsedMs": 842,
    "mode": "Basic",
    "credits": {
      "charged": 1,
      "remaining": 99,
      "bypassed": false
    }
  },
  "query": {
    "phone": "+14155550123"
  },
  "phone": {
    "e164": "+14155550123",
    "national": "(415) 555-0123",
    "country": "US",
    "areaCode": "415"
  },
  "identity": {
    "name": "Example Caller",
    "gender": null,
    "match": null
  },
  "line": {
    "type": "mobile",
    "carrier": "Example Wireless"
  },
  "availability": {
    "imessage": null,
    "whatsapp": null
  },
  "disclaimer": "For informational purposes only. Data may be incomplete, delayed, or inaccurate. Do not use it as the sole basis for personal, legal, financial, or safety decisions."
}
Use this endpoint to look up caller context for a US phone number.

Authorizations

X-API-Key
string
header
required

Send your provided API key in the X-API-Key header.

Headers

X-API-Key
string
required

Your provided CallHeater API key.

Query Parameters

phone
string
required

US phone number to look up. Formatting characters are accepted.

Examples:

"4155550123"

"+14155550123"

mode
enum<string>
default:Basic

Lookup depth. Basic aliases include basic and B; Deep Research aliases include deepresearch, D, and DR.

Available options:
Basic,
DeepResearch
display
enum<string>
default:json

Response format.

Available options:
json,
pretty
realestate
boolean
default:false

Include real estate market info in pretty responses.

sports
boolean
default:false

Include local sports team information for the phone number area code when available.

Response

Lookup result. JSON is returned by default; plain text is returned when display=pretty.

Structured lookup response. Available fields vary by lookup mode and source availability.

meta
object
query
object

The normalized request inputs.

phone
object
identity
object

Caller identity signals when available.

line
object

Carrier and line type signals when available.

availability
object

Messaging or service availability signals when available.

disclaimer
string