API Quickstart

Goal: get from "no API key" to "enrichment results in hand" in under 10 minutes. The public API is base-pathed at https://api.cleanlist.ai/api/v2.

Prerequisites

• A Cleanlist account at app.cleanlist.ai (opens in a new tab)
• A plan that includes API access

Step 1 — Generate an API key

1. Log in to app.cleanlist.ai (opens in a new tab)
2. Navigate to Settings → API Keys
3. Click Generate Key, name it (e.g. quickstart)
4. Copy the full key — it starts with clapi_ and is shown once

export CLEANLIST_API_KEY="clapi_your_actual_key"

Step 2 — Confirm the key works

GET /whoami is free and tells you who you are, your tier, your scopes, and which features your plan includes:

curl https://api.cleanlist.ai/api/v2/whoami \
  -H "Authorization: Bearer $CLEANLIST_API_KEY"

Step 3 — Check your credit balance

curl https://api.cleanlist.ai/api/v2/credits/balance \
  -H "Authorization: Bearer $CLEANLIST_API_KEY"

Step 4 — Enrich a person

POST /enrichment/person runs asynchronously and returns a workflow_id. It requires a lead_list_id (the list the enriched person is written to). Identify the person with one of: email, linkedin_url, person_id, or first_name + last_name + (company_name or domain). Set enrichment_type to partial (email, 1 credit), phone_only (10 credits), or full (email + phone, 11 credits).

curl -X POST https://api.cleanlist.ai/api/v2/enrichment/person \
  -H "Authorization: Bearer $CLEANLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_list_id": "YOUR_LIST_ID",
    "first_name": "John",
    "last_name": "Doe",
    "domain": "acme.com",
    "enrichment_type": "partial"
  }'

The response includes workflow_id, status: "pending", credits_reserved (an upfront cap — the unused portion is refunded at settle time), lead_list_id, and a poll_url.

Step 5 — Poll for the result

Poll GET /enrichment/status/{workflow_id} until the status is terminal. The response carries progress counters, the final result, and the actual credits_charged / credits_refunded.

curl https://api.cleanlist.ai/api/v2/enrichment/status/WORKFLOW_ID \
  -H "Authorization: Bearer $CLEANLIST_API_KEY"
# repeat until "status" is terminal: completed | completed_with_errors | failed | canceled | terminated

Step 6 — Scale to bulk

To enrich a whole list at once, first create/populate a list, then get a quote and run a bulk enrichment.

1. Estimate the cost — POST /credits/estimate with { "tool": "enrich_list", "list_id": "<id>", "scope": "partial" } returns a signed quote_id (valid ~5 minutes).
2. Run — POST /enrichment/bulk with { "list_id": "<id>", "scope": "partial", "quote_id": "<quote_id>" }. The bulk endpoint requires a quote_id. (Note the field is list_id here, not lead_list_id.)
3. Poll the returned workflow_id exactly as in Step 5.

See Credits & Quotes for the estimate/quote model and Lead Lists for creating and populating lists (including CSV import).

What you've built

1. ✓ A working clapi_ API key
2. ✓ A live identity + credit-balance check
3. ✓ An async person enrichment
4. ✓ A polling loop that reads results and final billing
5. ✓ A path to bulk enrichment with quotes

Related

• API Reference — full endpoint reference
• Authentication & Scopes
• Polling for Results — robust async patterns
• Errors & Rate Limits
• Troubleshooting