Audience: developers. API keys and the REST API are included on Pro and Enterprise (and legacy Pro and Scale plans), during the Pro trial and on every AppSumo tier. They are not available on Free or Starter. Support agent: confirm the user’s plan includes API access before giving API advice.
TL;DR: v1 enrichments are saved to the list you pass as the required lead_list_id: a list in your API key’s workspace that the key’s user can edit, with its normal per-list limit. Contacts already in it are skipped and not charged. v1 has one list-related endpoint, POST /folders. For full list management (create, read, rename, delete, add and remove leads), use the v2 lead-lists API.
Lead lists
Lead lists are how CluGTM organizes contacts in the app. The v1 API touches them in two ways: it saves every enrichment to the list you name with lead_list_id, and it can create folders.
The list v1 saves to
When you call POST /api/v1/public/enrich/bulk with a lead_list_id, CluGTM:
- Checks the list: it must be in your API key’s workspace, the key’s user must be able to edit it, and it can’t be your Extension Leads list.
- Skips contacts that are already in that list.
- Checks that the remaining contacts fit the list’s per-list contact limit.
- Saves the remaining contacts to the list and enriches them.
- Returns the
workflow_idandtask_ids.
To find a list’s id, open the list in the app and copy it from the URL (app.cleanlist.ai/lists/<id>), or use GET /api/v2/lead-lists. To make a new one, use POST /api/v2/lead-lists or create it in the app.
| Problem | Status | Code |
|---|---|---|
No lead_list_id, or one that isn’t a UUID | 422 | validation_error |
| The list isn’t in your workspace | 404 | list_not_found |
| You can view the list but not edit it | 403 | list_not_editable |
| The list is Extension Leads, which only collects people saved with the Chrome extension | 403 | extension_leads_locked |
| The new contacts would take the list past its per-list contact limit | 403 | PERMISSION_DENIED, with details.error lead_cap_reached |
Working with the results in the app
- Browse and filter the contacts in the list like any other list.
- Copy to another list: select contacts, then Actions → Copy to list.
- Export: download a CSV or send the contacts to a connected CRM from the Actions drawer. See Exporting data.
- Run skills: research or score the contacts with a skill.
Reading enriched contacts from code
You have three options:
- Webhook: pass
webhook_urland receive every contact’s result in one POST. See Webhooks. - Poll each task:
GET /api/v1/public/enrich/status?task_id=...returns one contact’s result (kept for 24 hours). See Enrichment. - Read the list:
GET /api/v2/lead-lists/{lead_list_id}/leadspages through the list with the full lead data (scopelists:read). See v2 lead lists.
Creating a folder
POST /api/v1/public/folders
Creates a folder for organizing lead lists, optionally inside another folder you created.
cURL
curl -X POST https://api.cleanlist.ai/api/v1/public/folders \
-H "Authorization: Bearer clapi_your_api_key" \
-H "Content-Type: application/json" \
-d '{"name": "Q4 Outbound"}'Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 1 to 255 characters. Leading and trailing spaces are trimmed |
parent_id | string (UUID) | No | A folder you created, to nest the new folder inside. Leave out for a top-level folder |
Response (201 Created)
{
"id": "b1e7c9d4-2f3a-4c8e-9a1b-6d5e4f3c2b1a",
"name": "Q4 Outbound",
"parent_id": null,
"user_id": "user_2abcJANEdoe456",
"organization_id": "org_2acmeIO789xyz",
"created_at": "2026-10-07T18:24:05Z"
}Errors
| Condition | Status | Message |
|---|---|---|
parent_id isn’t a valid UUID | 400 | “Invalid parent_id.” |
parent_id doesn’t exist or isn’t a folder you created | 404 | “Folder not found.” |
name missing, empty or longer than 255 characters | 422 | validation_error |
The folder appears under Lead Lists in the app. To put a list in it, drag the list onto the folder there. See Lead list folders.
POST /api/v1/public/folders always runs this v1 endpoint. The v2 API has its own folder endpoints at /api/v2/folders, which may not be available on every workspace.
Full list management
Creating, reading, renaming and deleting lists, and adding, removing or reading leads, are part of the v2 API:
| v2 endpoint | Purpose |
|---|---|
POST /api/v2/lead-lists | Create a list |
GET /api/v2/lead-lists | List your lists |
GET, PATCH, DELETE /api/v2/lead-lists/{id} | Read, rename or move, delete a list |
GET, POST, DELETE /api/v2/lead-lists/{id}/leads | Read, add or remove leads |
These need the lists:read or lists:write scope, and deleting a list or removing leads also needs the lists:delete opt-in scope on the key. Protected lists such as Extension Leads can’t be deleted. See v2 lead lists.