Skip to main content
GET
/
api
/
leads
/
check-availability
Check iMessage Availability (Single Lead)
curl --request GET \
  --url https://app.tuco.ai/api/leads/check-availability \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "leadId": "<string>",
  "available": true,
  "status": "<string>",
  "ghlContactId": {},
  "ghlLocationId": {},
  "hsPortalId": {},
  "hsContactId": {}
}

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.

Check iMessage availability for a single lead using their stored phone numbers and emails. Tuco checks every address on the lead (phone, email, altPhone1-3, altEmail1-3) and stops at the first one that is iMessage-capable. Updates the lead’s availabilityStatus field.
Don’t have a lead ID? Use GET /api/check-availability?address=+12025551234 to check any phone or email directly. No saved lead required.

​
Authentication

Authorization: Bearer tuco_sk_xxxxxxxxxxxxx

​
Query parameters

​
id
string
required
The lead’s ID (MongoDB ObjectId).Example: 667f1f77bcf86cd799439012

​
Example

curl "https://app.tuco.ai/api/leads/check-availability?id=667f1f77bcf86cd799439012" \
  -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx"

​
Success response (200)

{
  "success": true,
  "leadId": "667f1f77bcf86cd799439012",
  "available": true,
  "status": "available",
  "ghlContactId": "aMUQn0u0Z7cw0NQ7tJ5R",
  "ghlLocationId": "eL7DD22BdZ0rismu7qCA",
  "hsPortalId": null,
  "hsContactId": null
}
​
success
boolean
Always true on a 200 response.
​
leadId
string
The lead ID that was checked.
​
available
boolean
Whether the lead is reachable via iMessage.
​
status
string
One of:
  • "available" — at least one stored address supports iMessage
  • "unavailable" — none of the stored addresses support iMessage
  • "error" — the check failed (temporary issue)
​
ghlContactId
string | null
GoHighLevel contact ID, if linked.
​
ghlLocationId
string | null
GoHighLevel location ID, if linked.
​
hsPortalId
string | null
HubSpot portal ID, if linked.
​
hsContactId
string | null
HubSpot contact ID, if linked.
The same status is written back to the lead, so you can also read it via the Leads API.

​
Error responses

StatusWhenBody
400Missing id parameter{ "error": "Lead ID is required" }
401Invalid or missing API key{ "error": "Unauthorized" }
404Lead not found{ "error": "Lead not found" }
429API rate limit exceeded (200 req/min){ "error": "Rate limit exceeded" }
429All lines hit daily cap (70/day/line){ "error": "Daily availability check quota exhausted" }
500Internal server error{ "error": "Internal server error" }