Skip to main content
POST
Bulk Availability Check Endpoint

Endpoint

  • Method: POST
  • Path: /api/leads/check-availability
This endpoint lets you check iMessage availability for multiple leads at once, or for a single arbitrary address, using the same logic Tuco uses internally.

Request body

Send exactly one of address, 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.
Response

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.
Response (synchronous small batch)
For larger batches, Tuco automatically offloads work to a background job and responds with:
You can safely trigger this endpoint from your backend and then rely on the updated availabilityStatus field on each lead for downstream decisions (for example, whether to enroll a lead in an iMessage campaign or to prefer SMS/email).