Create Lead List
curl --request POST \
--url https://app.tuco.ai/api/lists \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"description": "<string>",
"contacts": [
{}
],
"source": "<string>",
"ghlLocationId": "<string>"
}
'import requests
url = "https://app.tuco.ai/api/lists"
payload = {
"name": "<string>",
"description": "<string>",
"contacts": [{}],
"source": "<string>",
"ghlLocationId": "<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({
name: '<string>',
description: '<string>',
contacts: [{}],
source: '<string>',
ghlLocationId: '<string>'
})
};
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 => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'contacts' => [
[
]
],
'source' => '<string>',
'ghlLocationId' => '<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/lists"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"contacts\": [\n {}\n ],\n \"source\": \"<string>\",\n \"ghlLocationId\": \"<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/lists")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"contacts\": [\n {}\n ],\n \"source\": \"<string>\",\n \"ghlLocationId\": \"<string>\"\n}")
.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::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"contacts\": [\n {}\n ],\n \"source\": \"<string>\",\n \"ghlLocationId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyLines & Leads
Create Lead List
Create a lead list in your Tuco workspace, optionally seeding it with contacts. Returns the listId used by the leads and availability endpoints.
POST
/
api
/
lists
Create Lead List
curl --request POST \
--url https://app.tuco.ai/api/lists \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"description": "<string>",
"contacts": [
{}
],
"source": "<string>",
"ghlLocationId": "<string>"
}
'import requests
url = "https://app.tuco.ai/api/lists"
payload = {
"name": "<string>",
"description": "<string>",
"contacts": [{}],
"source": "<string>",
"ghlLocationId": "<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({
name: '<string>',
description: '<string>',
contacts: [{}],
source: '<string>',
ghlLocationId: '<string>'
})
};
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 => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'contacts' => [
[
]
],
'source' => '<string>',
'ghlLocationId' => '<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/lists"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"contacts\": [\n {}\n ],\n \"source\": \"<string>\",\n \"ghlLocationId\": \"<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/lists")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"contacts\": [\n {}\n ],\n \"source\": \"<string>\",\n \"ghlLocationId\": \"<string>\"\n}")
.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::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"contacts\": [\n {}\n ],\n \"source\": \"<string>\",\n \"ghlLocationId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyA 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.contacts.
Authentication
Pass your workspace API key as a Bearer token, or use a Clerk session token.Authorization: Bearer tuco_xxxxxxxxxxxxx
Request body
List name. Must be unique in the workspace — a duplicate returns
400 List name already exists with code: "NAME_EXISTS". A missing or non-string name returns
400 with code: "NAME_REQUIRED".Optional. Seed the list with leads in the same call. Same per-lead shape as
POST /api/leads — firstName, lastName, phone, email,
companyName, customFields, and so on. Prefer phone in E.164 as the identifier.When present, the response is the import shape (listId, savedCount, duplicateCount)
rather than the list object.Origin label stored on the created leads, e.g.
"api" or "gohighlevel". Only used with contacts.GoHighLevel location id, stored on the created leads. Only applied when
source is "gohighlevel".Example — empty list
curl -X POST "https://app.tuco.ai/api/lists" \
-H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "name": "Q4 outbound", "description": "Sourced from the October webinar" }'
Success (200 OK)
{
"message": "List created successfully",
"list": {
"_id": "6ac3f1a271adb32c88d566f1",
"name": "Q4 outbound",
"description": "Sourced from the October webinar",
"workspaceId": "org_3CzFir0Fps4hHL4nbU9WQ6FR4ur",
"leadCount": 0,
"createdAt": "2026-10-05T19:02:10.004Z",
"updatedAt": "2026-10-05T19:02:10.004Z"
}
}
Example — create and seed in one call
curl -X POST "https://app.tuco.ai/api/lists" \
-H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Q4 outbound",
"contacts": [
{ "firstName": "Jane", "lastName": "Doe", "phone": "+14155551234" }
]
}'
Success (200 OK)
{
"listId": "6ac3f1a271adb32c88d566f1",
"savedCount": 1,
"duplicateCount": 0
}
Take
listId from either response shape and pass it to
POST /api/leads to add more leads later.Errors
| Status | When | Body |
|---|---|---|
400 | name missing or not a string | { "error": "List name is required", "code": "NAME_REQUIRED" } |
400 | A list with that name already exists | { "error": "List name already exists", "code": "NAME_EXISTS" } |
400 | A contact row is invalid | { "error": "...", "code": "INVALID_LEADS" } |
401 | Missing or invalid API key | { "error": "Unauthorized" } |
402 | Subscription past due (workspace read-only) | { "error": "READ_ONLY", "code": "READ_ONLY", "reason": "past_due" } |
429 | More than 120 requests/min for this workspace | { "error": "Rate limit exceeded" } |