How to Use the Cleanlist API in Clay (Step-by-Step)

Clay is powerful for building enrichment workflows. But if you have used it for a while, you know the problem: you chain together 5-6 enrichment providers, build fallback logic for each one, and still end up with gaps in your data. One provider has the email but not the phone. Another has the phone but it is a switchboard, not a direct dial.

Cleanlist solves this with a single API call. Instead of building your own waterfall in Clay across Hunter, RocketReach, Findymail, and others, the Cleanlist API handles the orchestration internally. It queries 15+ providers per contact, picks the best verified result from each, and returns one clean record.

This guide walks you through connecting the two.

What You Need Before Starting

• A Cleanlist account with an API key (sign up at app.cleanlist.ai, 30 free credits, no credit card)
• A Clay account on Explorer plan or above (HTTP API requires a paid Clay plan)
• A Clay table with contact data (first name, last name, and company domain or LinkedIn URL)

How the Cleanlist API Works

The Cleanlist enrichment API is asynchronous. You submit contacts, receive a workflow_id immediately, then poll a status endpoint for the completed results. Most single-contact enrichments finish in 2-5 seconds.

Here is the key information:

Input requirements (each contact needs one of these):

• linkedin_url on its own
• first_name + last_name + company_name or company_domain

Step 1: Get Your Cleanlist API Key

1. Sign up at app.cleanlist.ai
2. Go to Settings > API Keys
3. Click Generate API Key
4. Copy the key (starts with clapi_)

You get 30 free credits. No credit card required. Each enrichment uses 1 credit.

Step 2: Add an HTTP API Enrichment in Clay

1. Open your Clay table
2. Click the "+" button to add a new enrichment column
3. Search for "HTTP API" and select it
4. Switch to the Configure tab (skip the Generate tab for this setup)

Step 3: Configure the Enrichment Request

Fill in the Clay configuration panel with these values:

Method: POST

Endpoint URL:

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

Headers (add as key-value pairs):

JSON Body (using Clay's /Column Name syntax to reference your table columns):

{
  "enrichment_type": "full",
  "contacts": [
    {
      "first_name": "/First Name",
      "last_name": "/Last Name",
      "company_domain": "/Domain"
    }
  ]
}

If you have LinkedIn URLs instead of names:

{
  "enrichment_type": "full",
  "contacts": [
    {
      "linkedin_url": "/LinkedIn URL"
    }
  ]
}

Enrichment Type Options

Step 4: Set Rate Limiting

Cleanlist allows 60 requests per minute. In Clay's rate limiting fields:

• Request limit: 50
• Duration (ms): 60000

This keeps you safely under the cap.

Step 5: Enable "Required to Run"

Toggle Required to Run on your name and domain columns. This prevents Clay from firing the API on rows where those fields are empty, which saves credits.

Step 6: Handle the Async Response

Since Cleanlist's API is asynchronous, the first response returns a workflow ID, not the enriched data:

{
  "workflow_id": "wf_abc123",
  "status": "processing",
  "task_ids": ["task_xyz"],
  "total_contacts": 1
}

You need a second HTTP API column to poll for completed results:

1. Set Field Paths to Return on the first column to: task_ids.0
2. Add that value as a new column (call it "Task ID")
3. Add another HTTP API enrichment column with these settings:
   • Method: GET
   • URL: https://api.cleanlist.ai/api/v1/public/enrich/status?task_id=/Task ID
   • Headers: Same Authorization: Bearer clapi_your_api_key

Step 7: Map Enriched Data to Columns

Once the status endpoint returns completed data, click on the response cell and use Clay's "Add to Table" button. Select the fields you want as new columns.

Person fields:

Company fields:

Verification fields:

Alternative: Paste cURL for Faster Setup

If you want to skip manual configuration, copy this cURL and paste it into Clay's "Paste cURL" option:

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": "full",
    "contacts": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "company_domain": "acme.com"
      }
    ]
  }'

Clay's Sculptor will parse this and auto-fill the configuration. Then swap the static values ("Jane", "Smith", "acme.com") for column references (/First Name, /Last Name, /Domain).

Why Use Cleanlist Instead of Building a Waterfall in Clay

Clay lets you chain multiple enrichment providers together manually. That works, but it has real costs:

With a DIY waterfall, you pay for each provider step in Clay credits, even when earlier providers already found the data. With Cleanlist, you pay 1 credit per contact regardless of how many providers it queries internally.

For most teams, the single API call is simpler and cheaper. If you need to compare approaches in detail, see our data enrichment solutions comparison or the full Clay pricing breakdown.

Troubleshooting

Frequently Asked Questions

Can I use Cleanlist in Clay without the HTTP API?

Not directly. Cleanlist is not in Clay's native integrations marketplace, so the HTTP API enrichment is the way to connect them. The setup is straightforward and works the same way you would connect any custom API in Clay.

How much does this cost?

On the Cleanlist side, 1 enrichment = 1 credit. The free plan gives you 30 credits/month. Paid plans start at $29/month for 500 credits. On the Clay side, the HTTP API enrichment uses Clay credits based on your plan tier. See our full pricing page for details.

What is the difference between using Cleanlist's API vs using Clay's built-in enrichment providers?

Clay's built-in providers (Apollo, Clearbit, Hunter, etc.) each query one database. Cleanlist queries 15+ providers in a waterfall and returns the best verified result. In practice, this means higher match rates (95%+ vs 50-70% from a single source) and every email is verified before it reaches your table. See our enrichment API comparison for benchmarks.

Does Cleanlist verify emails automatically?

Yes. Every email returned through the API is triple-verified: syntax check, MX/DNS validation, and SMTP handshake. You do not need a separate email verification step in your Clay workflow. The verification.confidence field in the response tells you exactly how confident the result is.

Can I enrich in bulk or does it have to be one row at a time?

The API accepts up to 250 contacts per request. In Clay, the HTTP API enrichment runs once per row by default. For bulk enrichment outside of Clay, you can send batches directly to the API endpoint. For large lists, consider using the Cleanlist dashboard directly instead of routing through Clay.

Ready to try it? Get your free API key and connect it to Clay in under 10 minutes. If you want to see the full API documentation, visit docs.cleanlist.ai.