Skip to main content
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>"
  ]
}
'
{
  "success": true,
  "available": true,
  "address": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 emailThis endpoint (GET /api/check-availability?address=...)
Multiple phones/emails to check at oncePOST /api/check-availability (see below)
A saved lead IDGET /api/leads/check-availability
Multiple lead IDs or a listPOST /api/leads/check-availability
A phone + email and want round-robinPOST /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"
​
address
string
required
Phone number (E.164 format) or email address to check.Examples: +14155551234, frank@example.com

​
Response

{
  "success": true,
  "available": true,
  "address": "+14155551234"
}
​
success
boolean
Whether the API call completed without errors.
​
available
boolean
true if the address is registered on iMessage right now.
​
address
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" }'
​
address
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"]
  }'
​
addresses
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

LimitValue
API rate limit200 req/min per workspace
Daily cap70 checks/day per line (e.g., 3 lines = 210 checks)
Device gap3 seconds between checks on the same physical device

​
Error Codes

CodeWhenBody
400Missing or empty address param (GET){ "error": "Address parameter is required (phone or email)" }
400Missing both address and addresses (POST){ "error": "addresses array is required and must not be empty" }
400Too many addresses (POST, >100){ "error": "Maximum 100 addresses per request" }
401Invalid API key{ "error": "Unauthorized" }
429Rate limit exceeded{ "error": "Rate limit exceeded" }
429All lines hit daily cap{ "error": "Daily availability check quota exhausted" }
500Server error{ "error": "Internal server error" }