API reference

Number lookup

Find out if a phone number is iMessage-capable before sending. Saves wasted sends, warmup credits, and SMS-fallback costs.

Lookup a single number

POST/v1/lookup

Field	Type	Description
`phoneNumber`	string	Single E.164 or accepted format. Either this or `phoneNumbers`.
`phoneNumbers`	string[]	Array (1–100). Preferred for bulk; `/v1/lookup/bulk` is an alias.

curl -X POST 'https://api.bluereplies.com/v1/lookup' \
  -H "x-api-key: $BLUEREPLIES_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "phoneNumber": "+15551234567" }'

Lookup behaves differently from most endpoints — it queues a query against Apple IDS in the background and writes the result into our cache. The HTTP response is just an acknowledgement:

{
  "requestId": "msg_…",
  "phoneNumbers": ["+15551234567"],
  "status": "processing",
  "message": "Lookup request queued. Results populate the cache; query /v1/lookup/public to read them."
}

To get results synchronously, use the unauthenticated POST /v1/lookup/public with body { "phoneNumbers": [...] }. It returns cached results immediately (sub-second). The typical pattern: hit the authenticated /v1/lookup to prefetch + cache, then hit /v1/lookup/public to read the cached value.

Bulk lookup

POST/v1/lookup/bulk

Check up to 100 numbers in one request. Returns an array in input order.

{
  "phoneNumbers": ["+15551111111", "+15552222222", "+15553333333"]
}

Caching

We cache lookup results for 7 days. Repeated lookups against the same number within that window are essentially free and instant.

Pricing

Lookups are billed at $0.001 per uncached query. Cached results don't bill. Bulk requests bill per uncached number, not per request.