API Reference · file

Enrich CSV files via API

Upload a CSV of up to 100,000 rows and get back an enriched CSV — verified emails, phone numbers, titles, firmographics, and ICP scores appended as new columns. No code required. Processing 10K rows takes under 2 minutes.

Endpoint

POST https://api.cleanlist.ai/v1/enrich/csv_row

Request

POST https://api.cleanlist.ai/v1/enrich/csv_row
Authorization: Bearer clnl_live_...
Content-Type: application/json

{
  "email": "jane@acme.com"
}

Response

{
  "id": "ev_b8v2mn6",
  "status": "completed",
  "csv_row": {
    "row_id": 1,
    "input_email": "alex@startup.io",
    "input_name": "Alex Rivera",
    "enriched_email_status": "valid",
    "enriched_title": "CTO",
    "enriched_seniority": "c_level",
    "enriched_company": "Startup.io",
    "enriched_industry": "SaaS",
    "enriched_size": "11-50",
    "enriched_phone": "+1-650-555-0173",
    "enriched_linkedin": "https://linkedin.com/in/alexrivera",
    "icp_score": 72
  },
  "meta": {
    "credits_used": 11,
    "providers_queried": 15,
    "providers_matched": 5,
    "confidence": 0.88,
    "row_number": 1,
    "total_rows": 500
  }
}

Field reference

Field	Type	Description
row_id	integer	Row number from the original CSV (1-indexed). Preserves original row ordering.
input_email	string	The email address from the original CSV used as the primary lookup key.
input_name	string	Name from the original CSV, used as a secondary identifier when email matching fails.
enriched_email_status	enum	Verification result for the input email: valid, invalid, risky, catch-all, disposable, role-based, unknown.
enriched_title	string	Current job title, normalized to standard form.
enriched_seniority	enum	Seniority level classification: entry through c_level.
enriched_company	string	Current employer name.
enriched_industry	string	Industry classification.
enriched_size	string	Company employee count range.
enriched_phone	string	Direct dial or mobile phone number.
enriched_linkedin	string	LinkedIn profile URL.
icp_score	integer	0-100 ICP fit score, if ICP criteria are configured.

Code samples

curl

curl -X POST https://api.cleanlist.ai/v1/enrich/csv_row \
  -H "Authorization: Bearer $CLEANLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@acme.com"}'

Node.js

import Cleanlist from "cleanlist";

const client = new Cleanlist(process.env.CLEANLIST_API_KEY);

const result = await client.enrich.csv_row({
  email: "jane@acme.com",
});
console.log(result.csv_row.title);

Python

from cleanlist import Cleanlist

client = Cleanlist(api_key=os.environ["CLEANLIST_API_KEY"])

result = client.enrich.csv_row(email="jane@acme.com")
print(result["csv_row"]["title"])

Common use cases

Event lead enrichment

Export badge scans from a conference as CSV. Upload to Cleanlist, get back enriched records with verified emails, titles, and company data within hours — ready to import into your CRM or sequencer.

Purchased list cleaning

Before importing a purchased lead list into your CRM, upload the CSV for enrichment. Invalid emails are flagged, missing fields are filled, and every record gets an ICP score so you only import qualified leads.

Quarterly CRM export cleanup

Export your CRM contacts as CSV, run through enrichment to catch job changes, verify stale emails, and fill field gaps. Re-import the enriched CSV to bring your database back to 90%+ completeness.

Agency client onboarding

When a new client hands you a prospect CSV, enrich it in bulk before building campaigns. Deliver a clean, scored, verified list on day one instead of spending a week on manual research.

Pricing

Credit-based, no per-seat fees. This endpoint uses the standard enrichment rate:

Email only: 1 credit per enriched csv_row.
Email + phone: 11 credits per enriched csv_row.
Free tier: 30 credits/mo. See all pricing.

FAQ

What CSV format does the endpoint accept?

The endpoint accepts standard CSV files with headers. At minimum, include an 'email' column. Additional columns like 'first_name', 'last_name', 'company', and 'linkedin_url' improve match rates. Cleanlist auto-detects column names and maps them to input fields. UTF-8 encoding is required.

What happens to rows where enrichment finds no match?

Unmatched rows are returned in the output CSV with empty enrichment columns and a status of 'not_found'. No credits are charged for unmatched rows. The original input data is always preserved so you never lose source information.

How large can a CSV upload be?

The API accepts CSV files up to 100,000 rows per upload. Files under 10,000 rows process synchronously and return results immediately. Larger files process asynchronously — you receive a job_id and a webhook fires when processing completes. There is no file size limit beyond the row count.

Can I choose which fields to enrich?

Yes. Use the 'fields' parameter to specify which enrichment fields you want. Requesting email-only fields costs 1 credit per row. Adding phone fields costs 11 credits per row. You can also skip ICP scoring if you do not need it. This lets you control costs for different use cases.

Next steps

Full REST reference: /product/api.
Related glossary: data enrichment, waterfall enrichment.
Ready to ship? Start free with 30 credits.