API Reference

The Cleanlist Public API lets you run asynchronous contact enrichment with API keys.

Base URL

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

All endpoints use HTTPS. HTTP requests are rejected.

Quick Start

Get up and running in 3 steps:

1. Get Your API Key

Generate an API key from the Cleanlist portal (opens in a new tab):

Log in to portal.cleanlist.ai
Go to Settings -> API Keys
Click Generate Key
Copy your key (starts with clapi_)

2. Validate Your Key

curl https://api.cleanlist.ai/api/v1/public/auth/validate-key \
  -H "Authorization: Bearer clapi_your_api_key"

3. Start Your First Bulk Enrichment

Bulk enrichment supports up to 250 contacts per request.

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": [
      {
        "linkedin_url": "https://linkedin.com/in/johndoe",
        "first_name": "John",
        "last_name": "Doe",
        "company_domain": "acme.com"
      }
    ]
  }'

Enrichment runs asynchronously. You get workflow_id and task_ids immediately, then poll status.

API Sections

Section	Description
Authentication	API keys and request headers
Enrichment	Bulk enrichment, status polling, and webhooks

Key Concepts

Enrichment Types

Type	Behavior
`none`	Record preparation only (no new email/phone appended)
`partial`	Email enrichment
`phone_only`	Phone enrichment
`full`	Email + phone enrichment

Contact Input Requirement

For each contact in contacts, provide either:

linkedin_url
first_name + last_name + (company_name or company_domain)

Async Workflow

Call POST /enrich/bulk.
Store workflow_id and task_ids.
Poll GET /enrich/status with either workflow_id or task_id.
Optionally register webhooks to receive completion notifications.

Credits

Email enrichment: 1 credit per successful find
Phone enrichment: 10 credits per successful find
Failed enrichments: 0 credits charged

Rate Limits

Public API limit: 60 requests per minute per organization
Window type: fixed 60-second window
Exceeded limit response: 429 Too Many Requests
Retry guidance: respect the Retry-After response header

Response Format

All responses are JSON. Error responses follow this format:

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

Common status codes: 400 (bad request), 401 (unauthorized), 402 (insufficient credits), 404 (not found), 422 (validation error), 429 (rate limited), 500 (server error).

CRM Integrations Authentication