API Reference (Legacy v1)

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.

API access is included on Cleanlist's standard paid plans and on AppSumo Tier 5 (AppSumo Tiers 1–4 do not include it).

Base URL

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

All requests must use HTTPS. HTTP requests are rejected.

Core Public API endpoints

These are the most-used endpoints. The full /api/v1/public/* surface also covers lead-list management, people/company search, person/company enrichment, smart agents, CRM/sequencer sync, and data export — see the MCP API reference and the OpenAPI spec for the complete list.

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 Extension Leads 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 are wrapped in a single envelope with a stable UPPERCASE code:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "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)