> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getdial.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server.

# Look up what a number supports

> Ask whether any phone number in the world can receive iMessage, before you decide how to reach it.

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.

```bash
curl -G https://api.getdial.ai/api/v1/lookup \
  --data-urlencode "number=+14155550123" \
  -H "Authorization: Bearer $DIAL_API_KEY"
```

```json
{
  "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.

| Key        | Meaning                                                |
| ---------- | ------------------------------------------------------ |
| `imessage` | `true` 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`](/documentation/reference/errors) 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:

```bash
# 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](/documentation/capabilities/send-an-sms) — the lookup tells you which rail to pick, not whether the person is reachable at all.