Get started with the Cleanlist API to programmatically enrich leads, check credits, and receive webhook callbacks.
Base URL
Authentication
All requests require a Bearer token in the Authorization header:
Authorization: Bearer clapi_your_api_key
Generate API keys in the Cleanlist portal under Settings > API Keys. You can have up to 10 active keys per organization. Keys start with the clapi_ prefix and are only shown once at creation time.
Available endpoints
Method | Path | Purpose |
GET | /auth/validate-key | Verify your API key is valid |
GET | /credits/balance | Check your organization's credit balance |
POST | /enrich/bulk | Submit up to 250 contacts for enrichment |
GET | /enrich/status | Poll enrichment workflow status |
GET | /webhooks/deliveries | View webhook delivery attempt logs |
Quick example: Enrich contacts
Submit contacts for enrichment:
curl -X POST https://api.cleanlist.ai/api/v1/public/enrich/bulk \
-H "Authorization: Bearer clapi_your_key" \
-H "Content-Type: application/json" \
-d '{
"contacts": [
{"first_name": "Jane", "last_name": "Doe", "company_domain": "example.com"},
{"linkedin_url": "https://linkedin.com/in/johndoe"}
],
"enrichment_type": "partial"
}'
The API returns a workflow_id immediately. Results are processed asynchronously - poll the status endpoint or provide a webhook URL for callbacks.
Input requirements
Each contact requires either:
A LinkedIn URL, OR
First name + last name + (company domain OR company name)
Maximum 250 contacts per request. For larger batches, split into multiple requests.
Results
All API enrichment results appear in the DEFAULT lead list in the Cleanlist portal.
For the complete API reference, visit docs.cleanlist.ai.