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 is intentionally narrow — it covers enrichment, credits, and webhooks. Lead-list management lives in the portal, not in the API surface for clapi_ keys.

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 DEFAULT for your user
2. Creates one if it does not exist (is_protected: true, name: "DEFAULT", 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 DEFAULT lead 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 DEFAULT list yourself — it's managed for you.

Working with the DEFAULT list

Inside the portal:

• View results — Open the DEFAULT list to browse every contact you've enriched via the API
• Filter — Status (reliable, risky, 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)

Why the API doesn't expose list CRUD

Lead lists are tightly coupled to portal features (sharing rules, folders, smart columns, prospecting jobs, etc.) that don't map cleanly to a stateless REST surface. Rather than exposing a partial, leaky CRUD API, Cleanlist keeps list management inside the portal and reserves the Public API for the things programmatic clients actually need: enrichment and credit management.

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

Listing contacts you've enriched

There is no Public API endpoint that returns the contents of the DEFAULT list. To pull enriched results programmatically, you have two 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.

Protected lists

The DEFAULT 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