curl --request POST \
--url https://api.isnap.ai/v1/lookup \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"handle": "<string>",
"from_line_id": "<string>"
}
'import requests
url = "https://api.isnap.ai/v1/lookup"
payload = {
"handle": "<string>",
"from_line_id": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({handle: '<string>', from_line_id: '<string>'})
};
fetch('https://api.isnap.ai/v1/lookup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.isnap.ai/v1/lookup",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'handle' => '<string>',
'from_line_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.isnap.ai/v1/lookup"
payload := strings.NewReader("{\n \"handle\": \"<string>\",\n \"from_line_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.isnap.ai/v1/lookup")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"handle\": \"<string>\",\n \"from_line_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.isnap.ai/v1/lookup")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"handle\": \"<string>\",\n \"from_line_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"handle": "<string>",
"imessage": true,
"pending": true,
"probe_id": "<string>",
"retry_after": 2
},
"trace_id": "<string>",
"request_id": "<string>"
}{
"success": true,
"data": {
"handle": "<string>",
"imessage": true,
"pending": true,
"probe_id": "<string>",
"retry_after": 2
},
"trace_id": "<string>",
"request_id": "<string>"
}{
"success": false,
"data": "<unknown>",
"error": {
"status": 123,
"code": "<string>",
"message": "<string>",
"retry_after": 123,
"retry_at": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>",
"min": 123,
"max": 123
}
]
},
"trace_id": "<string>",
"request_id": "<string>"
}{
"success": false,
"data": "<unknown>",
"error": {
"status": 123,
"code": "<string>",
"message": "<string>",
"retry_after": 123,
"retry_at": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>",
"min": 123,
"max": 123
}
]
},
"trace_id": "<string>",
"request_id": "<string>"
}{
"success": false,
"data": "<unknown>",
"error": {
"status": 123,
"code": "<string>",
"message": "<string>",
"retry_after": 123,
"retry_at": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>",
"min": 123,
"max": 123
}
]
},
"trace_id": "<string>",
"request_id": "<string>"
}{
"success": false,
"data": "<unknown>",
"error": {
"status": 123,
"code": "<string>",
"message": "<string>",
"retry_after": 123,
"retry_at": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>",
"min": 123,
"max": 123
}
]
},
"trace_id": "<string>",
"request_id": "<string>"
}Look up a recipient
Tells whether a phone number or an email address can receive iMessage.
curl --request POST \
--url https://api.isnap.ai/v1/lookup \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"handle": "<string>",
"from_line_id": "<string>"
}
'import requests
url = "https://api.isnap.ai/v1/lookup"
payload = {
"handle": "<string>",
"from_line_id": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({handle: '<string>', from_line_id: '<string>'})
};
fetch('https://api.isnap.ai/v1/lookup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.isnap.ai/v1/lookup",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'handle' => '<string>',
'from_line_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.isnap.ai/v1/lookup"
payload := strings.NewReader("{\n \"handle\": \"<string>\",\n \"from_line_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.isnap.ai/v1/lookup")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"handle\": \"<string>\",\n \"from_line_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.isnap.ai/v1/lookup")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"handle\": \"<string>\",\n \"from_line_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"handle": "<string>",
"imessage": true,
"pending": true,
"probe_id": "<string>",
"retry_after": 2
},
"trace_id": "<string>",
"request_id": "<string>"
}{
"success": true,
"data": {
"handle": "<string>",
"imessage": true,
"pending": true,
"probe_id": "<string>",
"retry_after": 2
},
"trace_id": "<string>",
"request_id": "<string>"
}{
"success": false,
"data": "<unknown>",
"error": {
"status": 123,
"code": "<string>",
"message": "<string>",
"retry_after": 123,
"retry_at": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>",
"min": 123,
"max": 123
}
]
},
"trace_id": "<string>",
"request_id": "<string>"
}{
"success": false,
"data": "<unknown>",
"error": {
"status": 123,
"code": "<string>",
"message": "<string>",
"retry_after": 123,
"retry_at": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>",
"min": 123,
"max": 123
}
]
},
"trace_id": "<string>",
"request_id": "<string>"
}{
"success": false,
"data": "<unknown>",
"error": {
"status": 123,
"code": "<string>",
"message": "<string>",
"retry_after": 123,
"retry_at": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>",
"min": 123,
"max": 123
}
]
},
"trace_id": "<string>",
"request_id": "<string>"
}{
"success": false,
"data": "<unknown>",
"error": {
"status": 123,
"code": "<string>",
"message": "<string>",
"retry_after": 123,
"retry_at": "<string>",
"issues": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>",
"min": 123,
"max": 123
}
]
},
"trace_id": "<string>",
"request_id": "<string>"
}- 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:
200withimessagetrue,falseornull, or202withpending: truewhen a check was started and has given no definite answer: resend the same request afterretry_afterseconds. A call that starts a check waits up to 3 seconds for the device’s answer before it returns202. 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, a202and a repeat of a pending check count against every limit that applies to the call. A call refused with429 lookup_rate_limit_exceededcounts 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 with400or404counts against no limit. See Limits.
Errors
| Status | error.code | When |
|---|---|---|
| 400 | validation_failed | handle is shorter than 3 or longer than 255 characters, or is not a valid phone number or email address. from_line_id is malformed. |
| 404 | not_found | from_line_id is not a line of your account. |
| 429 | lookup_rate_limit_exceeded | A lookup limit is reached. Retry-After gives the seconds until the next UTC hour or the next UTC day. |
Authorizations
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
The handle to check.
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.
3 - 255A 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.
^line_[0-9A-Za-z]{25}$Response
The answer: imessage is true, false, or null when unknown.
Always true on a success response.
true The answer of a lookup, or the state of a check that is running.
Show child attributes
Show child attributes
Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap.
Id of the request that produced this response: req_ followed by 25 letters or digits.