Lists API

Manage lead lists and folders.

Lists are collections of leads. You can create lists manually, from scrape jobs, or by filtering existing leads. Lists can be organized into folders.

GET/api/listsSession

Get all lists for the organization

Parameters

folderIdstringFilter by folder ID
searchstringSearch lists by name

Response

{
  "data": [
    {
      "id": "list-123",
      "name": "Q1 Sales Prospects",
      "leadCount": 500,
      "folderId": "folder-1",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:45:00Z"
    }
  ],
  "total": 15
}
POST/api/listsSession

Create a new list

Parameters

namestringrequiredList name
folderIdstringParent folder ID

Request

{
  "name": "Engineering Leaders",
  "folderId": "folder-1"
}

Response

{
  "id": "list-456",
  "name": "Engineering Leaders",
  "leadCount": 0,
  "folderId": "folder-1",
  "createdAt": "2024-01-25T09:00:00Z"
}
GET/api/lists/:idSession

Get a specific list with its leads

Parameters

idstringrequiredList ID
pagenumberPage number for leads pagination
limitnumberLeads per page (default: 50)

Response

{
  "id": "list-123",
  "name": "Q1 Sales Prospects",
  "leadCount": 500,
  "leads": [
    {
      "id": "lead-1",
      "linkedinUrl": "https://linkedin.com/in/johndoe",
      "firstName": "John",
      "lastName": "Doe",
      "title": "VP of Sales",
      "company": "Anthropic",
      "workEmail": "john@anthropic.com"
    }
  ],
  "total": 500,
  "page": 1,
  "totalPages": 10
}
GET/api/lists/:id/exportSession

Export list as CSV

Parameters

idstringrequiredList ID
DELETE/api/lists/:idSession

Delete a list

Parameters

idstringrequiredList ID

Folder Management

GET/api/lists/foldersSession

Get all folders

Response

{
  "data": [
    {
      "id": "folder-1",
      "name": "Sales",
      "listCount": 5
    }
  ]
}
POST/api/lists/foldersSession

Create a new folder

Parameters

namestringrequiredFolder name

Request

{
  "name": "Marketing Campaigns"
}