Bulk Availability Check Endpoint
curl --request POST \
--url https://app.tuco.ai/api/leads/check-availability \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"address": "<string>",
"leadIds": [
"<string>"
],
"listId": "<string>"
}
'import requests
url = "https://app.tuco.ai/api/leads/check-availability"
payload = {
"address": "<string>",
"leadIds": ["<string>"],
"listId": "<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({address: '<string>', leadIds: ['<string>'], listId: '<string>'})
};
fetch('https://app.tuco.ai/api/leads/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/leads/check-availability",
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([
'address' => '<string>',
'leadIds' => [
'<string>'
],
'listId' => '<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/leads/check-availability"
payload := strings.NewReader("{\n \"address\": \"<string>\",\n \"leadIds\": [\n \"<string>\"\n ],\n \"listId\": \"<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://app.tuco.ai/api/leads/check-availability")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"address\": \"<string>\",\n \"leadIds\": [\n \"<string>\"\n ],\n \"listId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/leads/check-availability")
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 \"address\": \"<string>\",\n \"leadIds\": [\n \"<string>\"\n ],\n \"listId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyiMessage Availability
Bulk Availability Check Endpoint
Bulk-check iMessage availability for many leads or a single address. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full.
POST
/
api
/
leads
/
check-availability
Bulk Availability Check Endpoint
curl --request POST \
--url https://app.tuco.ai/api/leads/check-availability \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"address": "<string>",
"leadIds": [
"<string>"
],
"listId": "<string>"
}
'import requests
url = "https://app.tuco.ai/api/leads/check-availability"
payload = {
"address": "<string>",
"leadIds": ["<string>"],
"listId": "<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({address: '<string>', leadIds: ['<string>'], listId: '<string>'})
};
fetch('https://app.tuco.ai/api/leads/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/leads/check-availability",
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([
'address' => '<string>',
'leadIds' => [
'<string>'
],
'listId' => '<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/leads/check-availability"
payload := strings.NewReader("{\n \"address\": \"<string>\",\n \"leadIds\": [\n \"<string>\"\n ],\n \"listId\": \"<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://app.tuco.ai/api/leads/check-availability")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"address\": \"<string>\",\n \"leadIds\": [\n \"<string>\"\n ],\n \"listId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/leads/check-availability")
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 \"address\": \"<string>\",\n \"leadIds\": [\n \"<string>\"\n ],\n \"listId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyEndpoint
- Method:
POST - Path:
/api/leads/check-availability
Request body
Send exactly one ofaddress, leadIds or listId. They are checked in that order.
string
A single phone number (E.164) or email to check without creating a lead. Prefer a phone
number — an email only resolves if it is registered to an Apple account.Must be non-empty:
{ "address": "" } is ignored and the request falls through to the bulk
path, which then 404s if you supplied no leadIds or listId.string[]
Lead ids in this workspace to check. Each lead’s phone, email and
altPhone1-3 / altEmail1-3
are tried in order, stopping at the first address that is reachable.string
Check every lead in a list instead of naming them. Get a list id from
GET /api/lists.Check a Single Address (Quick Check)
Use this form to check one phone number or email address without creating a lead.The
address field must be a non-empty string. Sending { "address": "" } will not work — the empty string is ignored and Tuco falls through to the bulk leads path, which will likely return a 404 if you haven’t provided leadIds or listId.{
"address": "+12025551234"
}
{
"success": true,
"available": true,
"address": "+12025551234"
}
Bulk Check by Lead IDs
Provide a list of lead IDs in the current workspace. Tuco will:- Mark each lead as
availabilityStatus: "available","unavailable", or"error". - Return a summary of how many checks succeeded or failed.
{
"leadIds": [
"667f1f77bcf86cd799439012",
"667f1f77bcf86cd799439013",
"667f1f77bcf86cd799439014"
]
}
{
"success": true,
"checked": 3,
"successful": 3,
"errors": 0,
"results": [
{
"leadId": "667f1f77bcf86cd799439012",
"available": true,
"status": "available"
},
{
"leadId": "667f1f77bcf86cd799439013",
"available": false,
"status": "unavailable"
}
],
"processingMode": "synchronous"
}
{
"success": true,
"message": "Bulk availability check started in background",
"jobId": "bulk-availability-2025-10-15T14:30:00.000Z",
"checked": 1200,
"processingMode": "background"
}
availabilityStatus field on each lead for downstream decisions (for example, whether to enroll a lead in an iMessage campaign or to prefer SMS/email).