List Lead Lists
curl --request GET \
--url https://app.tuco.ai/api/lists \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.tuco.ai/api/lists"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.tuco.ai/api/lists', 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/lists",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/lists"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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/lists")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/lists")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"lists": [
{
"_id": "<string>",
"name": "<string>",
"description": "<string>",
"leadCount": 123,
"createdByUserId": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>"
}
]
}Lines & Leads
List Lead Lists
List every lead list in your Tuco workspace with its lead count — the source of the listId used when creating leads or running a bulk availability check.
GET
/
api
/
lists
List Lead Lists
curl --request GET \
--url https://app.tuco.ai/api/lists \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.tuco.ai/api/lists"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.tuco.ai/api/lists', 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/lists",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/lists"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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/lists")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/lists")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"lists": [
{
"_id": "<string>",
"name": "<string>",
"description": "<string>",
"leadCount": 123,
"createdByUserId": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>"
}
]
}A list owns leads.
listId is what you pass to
POST /api/leads to file new leads somewhere specific, and to
POST /api/leads/check-availability to check a
whole list at once. These endpoints are how you get a listId without opening the dashboard.Authentication
Pass your workspace API key as a Bearer token, or use a Clerk session token.Authorization: Bearer tuco_xxxxxxxxxxxxx
Example
curl "https://app.tuco.ai/api/lists" \
-H "Authorization: Bearer tuco_xxxxxxxxxxxxx"
Success (200 OK)
{
"lists": [
{
"_id": "6aab49a066aa3784fa345a0a",
"name": "Close Import",
"description": "Contacts imported from Close",
"workspaceId": "org_3CzFir0Fps4hHL4nbU9WQ6FR4ur",
"createdByUserId": "user_34tKD7C7oYWFSBH4JBvbSgO8de5",
"leadCount": 4,
"createdAt": "2026-09-17T02:00:00.189Z",
"updatedAt": "2026-09-21T16:50:19.878Z"
}
]
}
The Quick Sends list is created on the first call if it does not exist, so this endpoint never
returns an empty array. Quick Sends is where leads go when you send to a phone number that has no
saved lead yet, and when you omit
listId on POST /api/leads.Response
object[]
Every list in the workspace, newest first.
Errors
| Status | When | Body |
|---|---|---|
401 | Missing or invalid API key | { "error": "Unauthorized" } |
429 | More than 120 requests/min for this workspace | { "error": "Rate limit exceeded" } |