API Reference

The Cleanlist Public API lets you enrich contacts, check your credit balance, and receive enrichment results programmatically. It is a stable, versioned surface designed to be embedded into CRMs, outbound tooling, ETL jobs, and internal workflows.

Base URL

https://api.cleanlist.ai/api/v1/public

All requests must use HTTPS. HTTP requests are rejected.

The 5 Public API endpoints

That's the entire externally-exposed surface. Lead-list management, smart columns, ICP profiles, and CRM sync are available inside the Cleanlist portal (opens in a new tab) but are not part of the Public API.

Quick Start

1. Get your API key

1. Log in to portal.cleanlist.ai (opens in a new tab)
2. Go to Settings → API Keys
3. Click Generate Key
4. Copy the key — it starts with clapi_ and is shown only once

You can have up to 10 active keys per user. See Authentication for full details.

2. Check your credit balance

curl https://api.cleanlist.ai/api/v1/public/credits/balance \
  -H "Authorization: Bearer clapi_your_api_key"

3. Enrich your first batch

curl -X POST https://api.cleanlist.ai/api/v1/public/enrich/bulk \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "enrichment_type": "partial",
    "contacts": [
      {
        "first_name": "John",
        "last_name": "Doe",
        "company_domain": "acme.com"
      },
      {
        "linkedin_url": "https://www.linkedin.com/in/janedoe"
      }
    ]
  }'

The response contains a workflow_id. Enrichment runs in the background — see Enrichment for how to retrieve results.

API Sections

Key Concepts

Asynchronous enrichment

POST /enrich/bulk returns immediately with a workflow_id. The actual enrichment runs through Cleanlist's waterfall system across multiple providers. You can:

• Poll GET /enrich/status?workflow_id=... until status is completed or completed_with_errors, or
• Receive a callback by passing webhook_url in the bulk request — Cleanlist will POST the full result set when the workflow finishes.

Credits

Credits are deducted from your organization's balance only when an enrichment succeeds. Common costs:

See Credits for full pricing and how to handle insufficient-credit errors.

Lead lists

Public API enrichments are automatically grouped into a system-managed lead list named DEFAULT so they remain visible inside the Cleanlist portal. You don't need to create or manage this list yourself — see Lead Lists for details.

Response format

Successful responses return JSON. Error responses use FastAPI's standard format:

{
  "detail": "Error message describing what went wrong"
}

Common status codes:

See Errors for the complete reference.

Learn more

• Waterfall enrichment — how Cleanlist combines multiple providers
• Pricing — credit-based pricing details
• Cleanlist product overview (opens in a new tab)