API Quickstart

The Cleanlist API quickstart needs one clapi_ key from Settings → API keys, one POST /api/v2/enrichment/person and a poll of /api/v2/enrichment/status/{workflow_id}. A lookup that finds nothing costs 0 credits.

Goal: get from "no API key" to "enrichment results in hand" in under 10 minutes. API v2 is served 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 (see above)
• A lead list to write results into (create one in the app, or with POST /api/v2/lead-lists)

Step 1: Create an API key

1. Open app.cleanlist.ai (opens in a new tab).
2. Go to Settings → API keys.
3. Under Create API key, enter a Name (for example quickstart) and, if you want, an Expiry.
4. Click Create API key.
5. Copy the key shown under New API key. It starts with clapi_ and is shown once.

export CLEANLIST_API_KEY="clapi_your_actual_key"

If your plan doesn't include API access, creating a key through POST /api/v1/api-keys returns 403 with this body:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "This feature requires the Pro plan or higher.",
    "details": {
      "error": "feature_gated",
      "feature": "api_access",
      "current_tier": "starter",
      "required_tier": "pro"
    }
  }
}

During a trial, API calls with a key return 403 with the message "Public API access is not included during the trial. Use the signed-in app or choose a paid plan."

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 and 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 part is refunded when the run settles), 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 and 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, create and fill 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, single use).
2. Run: POST /enrichment/bulk with { "list_id": "<id>", "scope": "partial", "quote_id": "<quote_id>" }. The bulk endpoint requires a quote_id. (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 quote model and Lead Lists for creating and filling lists (including CSV import). To find people first, see the People Finder API.

What you've built

1. A working clapi_ API key
2. A live identity and 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 v2 Introduction: full endpoint index
• Authentication & Scopes
• Polling for Results: robust async patterns
• Errors & Rate Limits
• Connect Cleanlist to Claude (MCP)
• Troubleshooting