Where do contacts enriched with the v1 API go?

To the lead list you pass as lead_list_id on POST /api/v1/public/enrich/bulk. It's required, and it must be a list in your API key's workspace that the key's user can edit.

Can v1 save to the Extension Leads list?

No. Extension Leads only collects people saved with the Chrome extension. Passing its id returns 403 extension_leads_locked; pass another list you can edit.

Does the list's size limit apply to v1 enrichments?

Yes. The list's per-list contact limit for your plan applies. A request whose new contacts would take the list past it fails with 403 PERMISSION_DENIED and lead_cap_reached in details.error, so use another list or create a new one.

Why didn't the API enrich a contact I sent again?

A contact that is already in the list you passed as lead_list_id is skipped and not charged again. If every contact in a request is already there, the request fails with 400 'All N prospects are duplicates already in this list.'

🔌

Audience: developers. API keys and the REST API are included on Pro and Enterprise (and legacy Pro and Scale plans) and on AppSumo Tiers 5 to 9. They are not available on Free, Starter, AppSumo Tiers 1 to 4 or during the Pro trial. 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_id and task_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_url and 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}/leads pages through the list with the full lead data (scope lists: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"}'

Python


import requests
 
r = requests.post(
    "https://api.cleanlist.ai/api/v1/public/folders",
    headers={"Authorization": "Bearer clapi_your_api_key"},
    json={"name": "Q4 Outbound"},
)
r.raise_for_status()
print(r.json()["id"])

JavaScript


const r = await fetch("https://api.cleanlist.ai/api/v1/public/folders", {
  method: "POST",
  headers: {
    Authorization: "Bearer clapi_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Q4 Outbound" }),
});
console.log(await r.json());

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.