Skip to main content
POST
Look up a recipient
  • Credential: an API key. A trial key returns 401 unauthorized. See Recipient lookup.
  • Line-scoped keys: the list of a line-scoped key is not applied: such a key can name any line of the account in from_line_id.
  • Test keys: a lookup with an isnap_test_ account key counts against the same lookup limits: see Test keys.
  • Idempotency-Key: not honored.
  • Events: none, also when a check finishes.
  • Personal data: the request and the response carry the handle, and the response says whether it can receive iMessage. A definite answer is kept 24 hours and returned to every caller of iSnap. Request it only when needed, do not copy it into logs, tickets or other tools, and refer to a contact by an id of your own.
  • Response: 200 with imessage true, false or null, or 202 with pending: true when a check was started and has given no definite answer: resend the same request after retry_after seconds. A call that starts a check waits up to 3 seconds for the device’s answer before it returns 202. See The three answers.
  • Limits: 400 calls per account per UTC day, and, with from_line_id, 30 per line per UTC hour and 100 per line per UTC day. Every call that passes validation counts: an answer from the 24-hour store, a 202 and a repeat of a pending check count against every limit that applies to the call. A call refused with 429 lookup_rate_limit_exceeded counts against the limit that refused it and the limits checked before it, in this order: the account limit, the hourly limit of the line, the daily limit of the line. A call refused with 400 or 404 counts against no limit. See Limits.

Errors

The errors that every operation shares are in Errors.

Authorizations

Authorization
string
header
required

An API key created in the iSnap dashboard, or a trial key, sent as Authorization: Bearer <key>. An API key starts with isnap_live_ or isnap_test_; both act on the same account, lines and billing. A trial key acts on its trial only.

Body

application/json

The handle to check.

handle
string
required

The handle to check: a phone number or an email address, 3 to 255 characters. A phone number without a country code is read as a US number.

Required string length: 3 - 255
from_line_id
string

A line of your account (line_ followed by 25 letters or digits). When given, only that line's device runs the check, and the limits per line apply. When omitted, any line of your account can run the check and only the limit per account applies.

Pattern: ^line_[0-9A-Za-z]{25}$

Response

The answer: imessage is true, false, or null when unknown.

success
enum<boolean>
required

Always true on a success response.

Available options:
true
data
object
required

The answer of a lookup, or the state of a check that is running.

trace_id
string
required

Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap.

request_id
string
required

Id of the request that produced this response: req_ followed by 25 letters or digits.