Check iMessage Availability (Single Address)
curl --request GET \
--url https://app.tuco.ai/api/check-availability \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"address": "<string>",
"addresses": [
"<string>"
]
}
'import requests
url = "https://app.tuco.ai/api/check-availability"
payload = {
"address": "<string>",
"addresses": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.get(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({address: '<string>', addresses: ['<string>']})
};
fetch('https://app.tuco.ai/api/check-availability', 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://app.tuco.ai/api/check-availability",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_POSTFIELDS => json_encode([
'address' => '<string>',
'addresses' => [
'<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://app.tuco.ai/api/check-availability"
payload := strings.NewReader("{\n \"address\": \"<string>\",\n \"addresses\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("GET", 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.get("https://app.tuco.ai/api/check-availability")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"address\": \"<string>\",\n \"addresses\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/check-availability")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"address\": \"<string>\",\n \"addresses\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"available": true,
"address": "<string>"
}iMessage Availability
Check iMessage Availability (Single Address)
Check if a phone number or email is on iMessage — no saved lead required. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON.
GET
/
api
/
check-availability
Check iMessage Availability (Single Address)
curl --request GET \
--url https://app.tuco.ai/api/check-availability \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"address": "<string>",
"addresses": [
"<string>"
]
}
'import requests
url = "https://app.tuco.ai/api/check-availability"
payload = {
"address": "<string>",
"addresses": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.get(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({address: '<string>', addresses: ['<string>']})
};
fetch('https://app.tuco.ai/api/check-availability', 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://app.tuco.ai/api/check-availability",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_POSTFIELDS => json_encode([
'address' => '<string>',
'addresses' => [
'<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://app.tuco.ai/api/check-availability"
payload := strings.NewReader("{\n \"address\": \"<string>\",\n \"addresses\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("GET", 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.get("https://app.tuco.ai/api/check-availability")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"address\": \"<string>\",\n \"addresses\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/check-availability")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"address\": \"<string>\",\n \"addresses\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"available": true,
"address": "<string>"
}The simplest way to check if a phone or email has iMessage. Just pass the address as a query parameter. No lead ID, no saved contact required.
Don’t know which endpoint to use? Start here. This is the one you want for a quick, one-off check.
| I have… | Use this |
|---|---|
| A phone number or email | This endpoint (GET /api/check-availability?address=...) |
| Multiple phones/emails to check at once | POST /api/check-availability (see below) |
| A saved lead ID | GET /api/leads/check-availability |
| Multiple lead IDs or a list | POST /api/leads/check-availability |
| A phone + email and want round-robin | POST /api/check-availability-rr |
Single Address Check
Request
curl "https://app.tuco.ai/api/check-availability?address=%2B14155551234" \
-H "Authorization: Bearer tuco_sk_YOUR_KEY"
string
required
Phone number (E.164 format) or email address to check.Examples:
+14155551234, frank@example.comResponse
{
"success": true,
"available": true,
"address": "+14155551234"
}
boolean
Whether the API call completed without errors.
boolean
true if the address is registered on iMessage right now.string
The address that was checked (echoed back).
Not available
{
"success": true,
"available": false,
"address": "+14155551234"
}
Single Address Check (POST)
POST /api/check-availability
You can also POST a single address instead of using the GET query param.
Request
curl -X POST https://app.tuco.ai/api/check-availability \
-H "Authorization: Bearer tuco_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "address": "+14155551234" }'
string
A single phone number or email to check. Mutually exclusive with
addresses.Response
{
"success": true,
"results": [
{ "address": "+14155551234", "available": true }
]
}
Batch Check (Multiple Addresses)
POST /api/check-availability
Check up to 100 addresses in a single request. Each address is checked sequentially (3s gap per device).
Request
curl -X POST https://app.tuco.ai/api/check-availability \
-H "Authorization: Bearer tuco_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"addresses": ["+14155551234", "+14155559999", "frank@example.com"]
}'
string[]
Array of phone numbers or emails to check. Max 100 per request. Mutually exclusive with
address.Response
{
"success": true,
"results": [
{ "address": "+14155551234", "available": true },
{ "address": "+14155559999", "available": false },
{ "address": "frank@example.com", "available": false }
]
}
Rate Limits
| Limit | Value |
|---|---|
| API rate limit | 200 req/min per workspace |
| Daily cap | 70 checks/day per line (e.g., 3 lines = 210 checks) |
| Device gap | 3 seconds between checks on the same physical device |
Error Codes
| Code | When | Body |
|---|---|---|
400 | Missing or empty address param (GET) | { "error": "Address parameter is required (phone or email)" } |
400 | Missing both address and addresses (POST) | { "error": "addresses array is required and must not be empty" } |
400 | Too many addresses (POST, >100) | { "error": "Maximum 100 addresses per request" } |
401 | Invalid API key | { "error": "Unauthorized" } |
429 | Rate limit exceeded | { "error": "Rate limit exceeded" } |
429 | All lines hit daily cap | { "error": "Daily availability check quota exhausted" } |
500 | Server error | { "error": "Internal server error" } |