API Reference · core

Enrich contacts via API

Pass an email or LinkedIn URL and get back 40+ verified fields — name, title, seniority, company firmographics, direct dial, mobile, and social profiles — all cross-checked across 15+ data providers in a single API call.

Endpoint

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

Request

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

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

Response

{
  "id": "ev_c9x2kf8",
  "status": "completed",
  "contact": {
    "email": "jane.smith@acme.com",
    "email_status": "valid",
    "first_name": "Jane",
    "last_name": "Smith",
    "title": "VP of Marketing",
    "seniority": "VP",
    "department": "Marketing",
    "linkedin_url": "https://linkedin.com/in/janesmith",
    "phone": "+1-415-555-0142",
    "phone_type": "direct_dial",
    "mobile": "+1-415-555-0198",
    "location": "San Francisco, CA",
    "company_name": "Acme Corp",
    "company_domain": "acme.com",
    "company_industry": "SaaS",
    "company_size": "201-500",
    "company_revenue": "$50M-$100M"
  },
  "meta": {
    "credits_used": 11,
    "providers_queried": 15,
    "providers_matched": 8,
    "confidence": 0.96,
    "enriched_at": "2026-04-15T14:32:01Z"
  }
}

Field reference

Field	Type	Description
email	string	Verified work email address. SMTP-checked against live mail server.
email_status	enum	Verification result: valid, invalid, risky, catch-all, disposable, role-based, unknown.
first_name	string	Contact's first name, cross-referenced across providers.
last_name	string	Contact's last name.
title	string	Current job title, normalized to standard form (e.g., 'VP of Sales' not 'VP, Sales & BD').
seniority	enum	Seniority level: entry, individual_contributor, manager, director, vp, c_level, owner.
department	string	Department classification: Sales, Marketing, Engineering, Operations, Finance, HR, etc.
linkedin_url	string	LinkedIn profile URL, validated for current employment match.
phone	string	Direct dial phone number in E.164 format.
phone_type	enum	Phone classification: direct_dial, mobile, hq_switchboard.
mobile	string	Mobile phone number, if available. Requires 11 credits.
location	string	City, state/province, country based on most recent employment data.
company_name	string	Current employer name, matched against corporate registries.
company_domain	string	Primary company website domain.
company_industry	string	Industry classification using SIC/NAICS mapping.
company_size	string	Employee count range: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001+.
company_revenue	string	Estimated annual revenue range.

Code samples

curl

curl -X POST https://api.cleanlist.ai/v1/enrich/contact \
  -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.contact({
  email: "jane@acme.com",
});
console.log(result.contact.title);

Python

from cleanlist import Cleanlist

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

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

Common use cases

Outbound prospecting

Pass a LinkedIn Sales Nav export of emails and get back verified contact records with direct dials, seniority, and company size — ready for sequencing.

CRM record completion

Enrich incomplete Salesforce or HubSpot contacts to fill title, phone, and firmographic gaps without manual research.

Lead routing and scoring

Use seniority, department, and company_size fields to auto-route inbound leads to the right rep and score against your ICP.

Event follow-up enrichment

Turn a badge-scan CSV of names and emails into fully enriched contact records within hours of the event ending.

Pricing

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

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

FAQ

What input does the contacts enrichment endpoint accept?

You can pass an email address, a LinkedIn URL, or a name + company combination. Email is the most reliable identifier and returns the highest match rate (98%+). LinkedIn URL match rate is 95%+. Name + company matching is approximately 85% depending on name uniqueness.

How many credits does contact enrichment cost?

Email-only enrichment costs 1 credit per contact. Full enrichment with phone numbers costs 11 credits per contact. Unmatched lookups do not consume credits. Free accounts receive 30 credits per month.

How is the email verified during enrichment?

Every email returned goes through triple verification: syntax validation, DNS/MX record check, and live SMTP handshake. Catch-all domains are flagged as 'risky' so you can decide whether to include them in outreach. The email_status field tells you the exact result.

What happens if a contact has changed jobs since the data was last updated?

Cleanlist queries 15+ providers in sequence and selects the most recently verified data. If a contact changed jobs, the waterfall typically picks up the new employer within 30-60 days. The enriched_at timestamp tells you when the data was last confirmed.

Can I enrich contacts in bulk via the API?

Yes. The API accepts batch requests of up to 1,000 contacts per call. For larger volumes, use the async batch endpoint which processes up to 100,000 contacts and sends a webhook when complete. CSV upload through the dashboard handles unlimited volumes.

Next steps

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