API Reference

The Cleanlist.ai 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.ai portal (opens in a new tab):

1. Log in to app.cleanlist.ai
2. Go to Settings -> API Keys
3. Click Generate Key
4. 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://www.linkedin.com/in/levon-adamyan/",
        "first_name": "Levon",
        "last_name": "Adamyan",
        "company_domain": "cleanlist.ai"
      }
    ]
  }'

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

API Sections

Key Concepts

Enrichment Types

Contact Input Requirement

For each contact in contacts, provide either:

• linkedin_url
• first_name + last_name + (company_name or company_domain)

Async Workflow

1. Call POST /enrich/bulk.
2. Store workflow_id and task_ids.
3. Poll GET /enrich/status with either workflow_id or task_id.
4. Optionally pass webhook_url in the bulk request to receive completion callbacks.

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).

Learn More

• Cleanlist product overview (opens in a new tab)