Lead Lists

Lead lists are how Cleanlist organizes enriched contacts inside the portal. They support folders, sharing, filtering, smart columns, exports, and CRM sync.

The Public API covers enrichment, credits, webhooks, and lead-list management — create, list, get, rename/move, delete, and read list contents are all available to clapi_ keys with the lists:read/lists:write scopes. Sharing and folder management remain in the portal.

How Public API enrichment maps to lead lists

When you call POST /api/v1/public/enrich/bulk, Cleanlist:

1. Looks up a protected lead list named Extension Leads for your user
2. Creates one if it does not exist (is_protected: true, name: "Extension Leads", origin: "public_api")
3. Attaches every enriched contact from the request to that list
4. Returns the workflow + task ids

This means every contact you enrich via the API is reachable in the portal under the Extension Leads list, with all the same features as portal-created lists (filtering, smart columns, exports, sharing, etc.).

You don't need to create or reference the Extension Leads list yourself — it's managed for you.

Working with the Extension Leads list

Inside the portal:

• View results — Open the Extension Leads list to browse every contact you've enriched via the API
• Filter — Status (verified, likely_valid, risky, invalid, unknown), date added, company, location, etc.
• Move to another list — Select contacts and use Move to list to organize them
• Export — Download as CSV or push to your CRM
• Add smart columns — Layer on AI-driven enrichments like company research or ICP fit scoring (see Smart Columns)

Lead-list endpoints

Lead-list CRUD is available to clapi_ keys and is served under both /api/v2 and the legacy /api/v1/public prefix: POST /lead-lists (create — idempotent on name, returning HTTP 200 with reused: true if a list of that name already exists), GET /lead-lists (list), GET /lead-lists/{id} (get), GET /lead-lists/{id}/leads (read contents), PATCH /lead-lists/{id} (rename/move), and DELETE /lead-lists/{id} (delete). Reads require the lists:read scope; writes require lists:write.

Portal-only features — sharing rules, folders, smart columns, and prospecting jobs — don't map cleanly to a stateless REST surface and remain in the portal.

If your use case requires more programmatic list manipulation, contact us — we'd like to hear about it.

Listing contacts you've enriched

To pull enriched results programmatically, you have three options:

Option 1 — Receive results via webhook (recommended)

Pass a webhook_url when you submit a bulk enrichment. Cleanlist will POST the complete result set (all enriched contacts, with email/phone/company data) to your endpoint when the workflow finishes.

{
  "enrichment_type": "partial",
  "webhook_url": "https://your-app.com/webhooks/cleanlist",
  "contacts": [...]
}

See Webhooks for the payload schema.

Option 2 — Poll the workflow status

Call GET /api/v1/public/enrich/status?workflow_id=... until status is completed. The response includes summary counts; for the full per-contact result, poll each task_id returned by the bulk endpoint.

See Enrichment for examples.

Option 3 — Read the list contents directly

Call GET /api/v1/public/lead-lists/{id}/leads (also served at /api/v2/lead-lists/{id}/leads) with the lists:read scope to page through a list's enriched contacts, including the Extension Leads list. The response is { list_id, leads: [...], total, cursor }; pass the returned cursor to fetch the next page.

Protected lists

The Extension Leads list is protected: it can't be deleted from the portal UI. If you want to clear it out, move the contacts elsewhere first or contact support. This protection exists so a stray click doesn't break your API integration.

Related

• Enrichment — submit and poll bulk enrichments
• Webhooks — receive results via callback
• Smart Columns — layer AI-driven enrichments on top of any list
• Lead List Folders — organize lists in the portal