Capabilities

Look up what a number supports

View as Markdown

Before you send, you can ask what a number can actually receive. It works on any number — not just the ones on your account, and not just ones you’ve messaged before.

curl -G https://api.getdial.ai/api/v1/lookup \
  --data-urlencode "number=+14155550123" \
  -H "Authorization: Bearer $DIAL_API_KEY"
{
  "number": "+14155550123",
  "supports": { "imessage": true }
}

Reading the answer

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.

KeyMeaning
imessagetrue when the number can currently receive iMessage.

More channels arrive as more keys. Read the ones you care about by name — supports.imessage — rather than assuming the whole set, so a new key never breaks your code.

It’s a point-in-time answer

This is a live check, not a stored property of the number. Someone who switches device or turns the service off stops being reachable, and the same number can answer differently next week.

true is a strong signal for choosing a channel. It is not a promise that a later send will be delivered — that still depends on the recipient’s device and network at the moment you send.

A failed lookup is never false

If Dial can’t complete the check, the request fails with a 502 rather than guessing. So a false always means we asked, and the number isn’t reachable there — never we couldn’t find out.

That distinction matters if you branch on the result: a 502 is worth retrying, a false isn’t.

Picking a channel with it

The common use is deciding how to reach someone before you spend a send:

# 1. Ask what the number supports.
curl -G https://api.getdial.ai/api/v1/lookup \
  --data-urlencode "number=+14155550123" \
  -H "Authorization: Bearer $DIAL_API_KEY"
# 2. Send on the channel it reported.
curl -X POST https://api.getdial.ai/api/v1/messages \
  -H "Authorization: Bearer $DIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+14155550123","fromNumber":"+14155550100","body":"Hi","channel":"imessage"}'

A number that doesn’t support iMessage can still be reached by SMS — the lookup tells you which rail to pick, not whether the person is reachable at all.