Look up what a number supports

View as Markdown
Ask what a phone number can receive, before you send to it. Works on any number in the world — it doesn't have to be one of your Dial numbers, and you don't have to have messaged it before. `supports` describes **the number you asked about**, not your own line. Each key is a channel, and the boolean says whether that number can be reached there. Today the only key is `imessage`; further channels arrive as further keys, so read the ones you care about by name rather than assuming the whole set. **The answer is point-in-time, not a property of the number.** `true` means the number is reachable on iMessage as of this request — someone who changes device or turns the service off stops being reachable, and the same number can answer differently next week. Treat it as a strong signal for picking a channel, not as a promise that a later send lands. **A lookup that fails is never reported as `false`.** If Dial can't complete the check the request fails with a `502`, so `false` always means "we asked, and the number isn't reachable there" — never "we couldn't find out".

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Query parameters

numberstringRequired

The number to look up, in E.164 — +14155550123. Spaces, dashes and parentheses are accepted and stripped; the normalized form comes back as number.

Response

What the number supports.
numberstring
The number you asked about, normalized to E.164.
supportsobject

One key per channel, true when the number can be reached there. Keys are added over time — read the ones you need by name.

Errors

400
Bad Request Error
401
Unauthorized Error
429
Too Many Requests Error
502
Bad Gateway Error