API reference

Is this number on iMessage?

A best guess from your own Messages history: what the newest chat with the person used.

GET/v1/lookup

A best guess from your own Messages history: what the newest chat with the person used. BlueBot asks the Mac and waits up to 15 seconds; basis says what the answer rests on. Apple offers no way to ask about a number you have never texted, so that answer is unknown.

Needs a key with the messages:read scope. Keys and scopes

Query parameters

numberstringrequired
The phone number or email address to look up.
3 to 320 characters.

Example

GET/v1/lookupIs this number on iMessage? →

curl "https://usebluebot.com/api/v1/lookup?number=%2B15555550123" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"

Response

200: The answer and its basis.

object"lookup"required
handlestringrequired
A phone number in E.164 (+15555550123) or an email address an Apple ID uses (iMessage only).
servicestringrequired
What the newest chat with the person used, or unknown.
One of imessage, sms, unknown.
basisstringrequired
history: a chat with the person was found. none: there is no chat with them. device_offline: the Mac wasn’t there to ask. timeout: the Mac didn’t answer within 15 seconds.
One of history, none, device_offline, timeout.
last_seen_attimestamp or nullrequired
The newest text in that chat.
checked_attimestamprequired
When this answer was found.

Response200

{
  "object": "lookup",
  "handle": "+15555550123",
  "service": "imessage",
  "basis": "history",
  "last_seen_at": "2026-11-12T16:20:00.000Z",
  "checked_at": "2026-11-13T19:41:00.000Z"
}

Errors

Every refusal has the same envelope and a page of its own. These are the ones this operation can give.

Code	Status	What it means
`unauthorized`	401	The request carried no key, or a key BlueBot doesn’t know: mistyped, revoked, or a test key sent to the live API.
`insufficient_scope`	403	The key doesn’t carry the scope the endpoint needs. Each endpoint’s reference names its scope.
`rate_limited`	429	Too many requests. A key may make 120 requests a minute. The `RateLimit` header says how many are left, and `Retry-After` how long to wait.
`internal`	500	Something went wrong on BlueBot’s side. It was reported. Send the request again; with an Idempotency-Key that is always safe.
`invalid_request`	400	Something in the request doesn’t fit: a missing or malformed field, a bad id, or a combination the endpoint refuses. `details` names each field.

Try it

Call this operation from the page with your own key. The key stays in this tab and is forgotten when you leave.