Lead Lists

Lead lists are how you organize contacts in CluGTM, the same Lead Lists you see in the app. API v2 exposes full CRUD plus CSV import.

Create

POST /lead-lists

Creates a private list in your workspace. Returns 201.

Create is idempotent on name (case-insensitive) for the same owner: if you already own a list with that name, no new list is created and the endpoint returns 200 with the existing list and reused: true.

Request body

curl -X POST https://api.cleanlist.ai/api/v2/lead-lists \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q3 Outbound: Fintech VPs"}'

{
  "list_id": "9c1f...",
  "name": "Q3 Outbound: Fintech VPs",
  "description": null,
  "lead_count": 0,
  "enriched_count": 0,
  "folder_id": null,
  "created_at": "2026-06-03T10:00:00Z",
  "timestamp_ms": 1717430400000
}

If your plan’s list limit is reached, create returns 403 list_cap_reached; delete a list or upgrade, then retry.

List

GET /lead-lists

Pages through the lists you can access: owned, organization-wide and shared.

{
  "lists": [
    {
      "list_id": "9c1f...",
      "name": "Q3 Outbound: Fintech VPs",
      "lead_count": 128,
      "folder_id": null,
      "created_at": "2026-06-03T10:00:00Z",
      "owner_name": "Your Name",
      "visibility": "private"
    }
  ],
  "total": 14,
  "cursor": "50",
  "timestamp_ms": 1717430400000
}

visibility is one of private, organization or shared. owner_name is the list creator’s display name (may be null).

Get one

GET /lead-lists/{list_id}

{
  "list_id": "9c1f...",
  "name": "Q3 Outbound: Fintech VPs",
  "description": null,
  "lead_count": 128,
  "enriched_count": 96,
  "folder_id": null,
  "created_at": "2026-06-03T10:00:00Z",
  "timestamp_ms": 1717430400000
}

A list that doesn’t exist, or that belongs to another workspace, returns 404 list_not_found.

Update

PATCH /lead-lists/{list_id}

Scope: lists:write

Rename a list, update its description, or move it to a different folder. Only the fields you send change. Returns the updated list object.

Request body

curl -X PATCH https://api.cleanlist.ai/api/v2/lead-lists/9c1f... \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q3 Outbound: Fintech VPs (revised)", "folder_id": "4b0e2c9a-..."}'

{
  "list_id": "9c1f...",
  "name": "Q3 Outbound: Fintech VPs (revised)",
  "description": null,
  "lead_count": 128,
  "enriched_count": 96,
  "folder_id": "4b0e2c9a-...",
  "created_at": "2026-06-03T10:00:00Z",
  "timestamp_ms": 1717430400000
}

A list shared with you as view-only returns 403 list_not_editable on any write.

Delete

DELETE /lead-lists/{list_id}

Scope: lists:write, and the key must have opted into lists:delete

Permanently deletes a list and removes all its lead memberships. Lead records that also belong to other lists stay in those lists. Returns HTTP 200 with a small confirmation body:

curl -X DELETE https://api.cleanlist.ai/api/v2/lead-lists/9c1f... \
  -H "Authorization: Bearer clapi_your_api_key"

{ "list_id": "9c1f...", "deleted": true, "timestamp_ms": 1717430400000 }

Deleting a list or removing its leads needs the lists:delete opt-in scope on top of lists:write. A key that hasn’t opted in gets 403 opt_in_scope_required with details.required_scope: "lists:delete", and nothing is deleted. Tick Delete lead lists and leads on the key under Settings → API keys → Permissions, or delete the list in CluGTM. The CluGTM MCP deletes only after the person approves in the host app’s own approval prompt; without it the call returns 403 approval_channel_required.

List leads

GET /lead-lists/{list_id}/leads

Pages through the leads in a list, newest first.

cursor and snapshot_id are opaque. Each walk reads one frozen order, so leads added while you page cause no duplicates or skips. Either keep passing cursor (it carries the snapshot), or pass snapshot_id plus an offset. If that snapshot has expired you get 409 snapshot_expired: start again without snapshot_id, offset or cursor. A lead deleted after the snapshot simply drops off its page.

Lead row schema

{
  "list_id": "9c1f...",
  "leads": [
    {
      "lead_id": "lead_abc",
      "first_name": "Jane",
      "last_name": "Doe",
      "full_name": "Jane Doe",
      "email": "jane@acme.com",
      "phone": "+14155550123",
      "title": "VP Sales",
      "company": "Acme",
      "company_id": "3f2b6c1d-8a4e-4b7f-9c2d-1e5a6b7c8d9e",
      "domain": "acme.com",
      "location": "San Francisco, California, United States",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe-9a1b",
      "provider": "leadmagic"
    }
  ],
  "total": 128,
  "cursor": "100:view:{9c1f...}:...",
  "snapshot_id": "view:{9c1f...}:...",
  "pending_imports": [],
  "pending_import_total": 0,
  "pending_import_cursor": null,
  "task_id": "cl-task_def...",
  "timestamp_ms": 1717430400000
}

email and phone follow your workspace’s reveal rules: a contact value your workspace hasn’t paid to reveal comes back null.

Pending imports

Rows from an import that haven’t become leads yet are returned separately, in pending_imports, never in leads. Each row has a raw_person_id (not a lead_id, so it can’t be used with add or remove), a status of pending, processing, failed or lookup_failed, the parsed identity fields (first_name, last_name, full_name, email, phone, title, company, company_domain, linkedin_url) and source_row_index. pending_import_total counts them and pending_import_cursor pages them; pass it as cursor with the same limit. Whole-list enrichment includes pending rows; an enrichment of selected lead_ids does not.

Add leads

POST /lead-lists/{list_id}/leads

The body takes exactly one of two forms (sending both, or neither, returns 422 validation_error). Adding by filter isn’t supported; run a search first and save its cohort.

Both forms take an optional idempotency_key (up to 128 characters). Re-sending the same add with the same key inserts once, so a retry after a timeout is safe. Omit it and the server makes a fresh key for each request.

# Save a search result: pass the cohort handle (task_id), not lead_ids
curl -X POST https://api.cleanlist.ai/api/v2/lead-lists/9c1f.../leads \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "cl-task_abc123", "entity_ids": ["4482910", "4482911"], "idempotency_key": "save-2026-11-10-d4e5f6"}'

# Add existing leads by id (for example, from another list)
curl -X POST https://api.cleanlist.ai/api/v2/lead-lists/9c1f.../leads \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lead_ids": ["lead_abc", "lead_def"]}'

{ "list_id": "9c1f...", "added": 2, "skipped_duplicates": 0, "credits_charged": 0 }

A cohort handle expires an hour after the search; an expired or unknown task_id returns 404. To check what a handle holds before saving it, read it with GET /tasks/{task_id}.

If the save would push the list past your plan’s per-list contact limit, you get 403 lead_cap_reached. If a saved profile conflicts with the search result (different company or role), you get 409 search_result_conflict.

Remove leads

DELETE /lead-lists/{list_id}/leads

Scope: lists:write, and the key must have opted into lists:delete (see Delete)

Removes leads from a list by lead_ids (up to 100). This removes membership only: the lead stays in your workspace and in any other lists. Unknown ids are ignored.

curl -X DELETE https://api.cleanlist.ai/api/v2/lead-lists/9c1f.../leads \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lead_ids": ["lead_abc"]}'

{ "list_id": "9c1f...", "removed": 1 }

CSV import

POST /lead-lists/{list_id}/csv-import

Imports a CSV into a list and can start bulk enrichment in the same call. Returns 201. Needs lists:write; if dispatch_enrichment is true, also enrich:write.

Request body

Response

{
  "list_id": "9c1f...",
  "rows_parsed": 500,
  "rows_imported": 488,
  "rows_skipped": 12,
  "skip_reasons": { "missing_required": 8, "duplicate_email": 4 },
  "sample_skip_rows": [3, 17, 42],
  "workflow_id": "bulk-enrich-9a1b...",
  "enrichment_status_url": "/api/v2/enrichment/status/bulk-enrich-9a1b...",
  "idempotency_replayed": false,
  "timestamp_ms": 1717430400000
}

B64=$(base64 -i leads.csv)
curl -X POST https://api.cleanlist.ai/api/v2/lead-lists/9c1f.../csv-import \
  -H "Authorization: Bearer clapi_your_api_key" -H "Content-Type: application/json" \
  -d "{
    \"csv_content_base64\": \"$B64\",
    \"column_mapping\": {\"first_name\": \"First\", \"last_name\": \"Last\", \"company_domain\": \"Domain\"},
    \"dispatch_enrichment\": true,
    \"enrichment_type\": \"partial\"
  }"

After a dispatching import, poll the returned enrichment_status_url; see Enrichment status. If CSV import is switched off for maintenance, the endpoint returns 503 not_enabled.

Find people at a list’s companies

POST /lead-lists/{list_id}/find-people starts an async job that finds people (by title, seniority and location) at companies already in the list and imports them into it. Discovery and import are free. Poll GET /lead-lists/{list_id}/find-people/status/{workflow_id}. Full reference: People Finder API.

Folders

Folders organize lists, the same folders as in the app’s Lead Lists page. Folders belong to the workspace: every member sees every folder, and any member can rename or delete one. You can file a list only into a folder you created (owned: true). All four endpoints are free.

GET /folders

Scope: lists:read

Returns every folder in the workspace as a flat list, with no paging. Build a tree from parent_id if you need one.

{
  "folders": [
    {
      "folder_id": "4b0e2c9a-...",
      "name": "Q3 Campaigns",
      "parent_id": null,
      "list_count": 4,
      "owned": true,
      "created_at": "2026-06-28T14:32:00"
    }
  ],
  "total": 1,
  "timestamp_ms": 1751404800000
}

POST /folders

Scope: lists:write · Returns 201

Creates a folder at the root. Body: name (required, 1 to 255 characters, trimmed). Create is idempotent on name: if you already own a folder with that name (case-insensitive), you get it back with reused: true instead of a duplicate.

curl -X POST https://api.cleanlist.ai/api/v2/folders \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q3 Campaigns"}'

{
  "folder_id": "4b0e2c9a-...",
  "name": "Q3 Campaigns",
  "parent_id": null,
  "list_count": 0,
  "owned": true,
  "created_at": "2026-06-28T14:32:00",
  "reused": false,
  "timestamp_ms": 1751404800000
}

PATCH /folders/{folder_id}

Scope: lists:write

Renames a folder. Body: name (1 to 255 characters). An empty body returns 422. Returns the same object as create.

DELETE /folders/{folder_id}

Scope: lists:write

Deletes a folder and its child folders. Lists inside are unfiled (moved to the root), never deleted. Because that moves other members’ lists too, a folder that still holds lists returns 409 folder_not_empty with details.list_count, unless you pass ?force=true.

curl -X DELETE "https://api.cleanlist.ai/api/v2/folders/4b0e2c9a-...?force=true" \
  -H "Authorization: Bearer clapi_your_api_key"

{
  "folder_id": "4b0e2c9a-...",
  "deleted": true,
  "lists_unfiled": 4,
  "message": "Folder deleted; 4 lists moved to the root.",
  "timestamp_ms": 1751404800000
}

The folder endpoints are live on /api/v2 but aren’t in the served OpenAPI spec yet; call them over HTTP as shown.

Learn more

• People Finder API
• Enrichment endpoints
• Enrichment types & pricing
• Credits & the quote model
• Export
• Polling & async results