Skip to main content
GET
/
api
/
leads
Get Leads Endpoint
curl --request GET \
  --url https://api.example.com/api/leads

​
Endpoint

  • Method: GET
  • Path: /api/leads
This endpoint returns leads in the active workspace, matching what you see in the Tuco UI.

​
Query Parameters

  • listId (string, optional) – restrict to a specific Tuco list.
  • search (string, optional) – case‑insensitive search on name, email, phone, or company.
  • page (number, optional, default 1) – page number.
  • limit (number, optional, default 50) – page size.
Example: 
GET /api/leads?listId=507f1f77bcf86cd799439011&search=john&page=1&limit=50
Authorization: Bearer <token>

​
Response

{
  "leads": [
    {
      "_id": "667f1f77bcf86cd799439012",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+12025551234",
      "companyName": "Acme Corp",
      "jobTitle": "CEO",
      "listId": "507f1f77bcf86cd799439011",
      "workspaceId": "org_123",
      "createdAt": "2025-10-14T10:30:00Z",
      "updatedAt": "2025-10-14T10:30:00Z"
    }
  ],
  "lists": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Prospects – October",
      "workspaceId": "org_123"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalCount": 1,
    "totalPages": 1
  }
}
No hidden changes are applied to your data by reading; this endpoint is read‑only from your point of view. Errors such as missing auth (401) or invalid query parameters (400) are returned with clear JSON messages.