Cleanlist

Authentication Type: API Key
Description: Bulk contact enrichment service. Submit contacts (by name + company or LinkedIn URL) and receive verified emails, phones, and firmographic data via an asynchronous workflow.

Authentication

To authenticate, you'll need a Cleanlist API key:

1. Log in to portal.cleanlist.ai
2. Navigate to Settings → API Keys
3. Click Generate Key, name it, and copy the full key (starts with clapi_) — it is shown only once
4. Provide it as the apiKey field

You'll also need a plan that includes API access and enough credits for the records you plan to enrich.

Enrichment

Submit and poll asynchronous enrichment workflows. The flow is: call Bulk Enrichment to start a workflow, then call Enrichment Status every 5–10 seconds until the workflow reaches a terminal state.

Bulk Enrichment

Submit a batch of contacts for asynchronous enrichment. Returns immediately with a workflow_id and a list of task_ids (one per submitted contact). Each contact can be identified either by name + company info or by a LinkedIn URL alone.

Operation Type: Mutation (Write)

Parameters:

• enrichment_type string (required): One of "none", "partial", "phone_only", "full", "prospecting_only". "partial" returns work email + standard fields; "full" includes personal emails; "none" validates only.
• contacts array of objects (required): The records to enrich. Costs credits per record.
  • first_name string (nullable): First name
  • last_name string (nullable): Last name
  • company_domain string (nullable): Employer domain (e.g., "acme.com") — strongest signal alongside name
  • company_name string (nullable): Employer name (use if domain is unknown)
  • linkedin_url string (nullable): LinkedIn profile URL — can be used alone with no name or company
  • email string (nullable): Known email; lets Cleanlist verify and append additional fields

Returns:

• workflow_id string: Workflow identifier — pass to cleanlist/enrich/status to poll for results
• task_ids array of strings: One task ID per submitted contact, in submission order

Example Usage:

{
  "enrichment_type": "partial",
  "contacts": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "company_domain": "acme.com"
    },
    {
      "linkedin_url": "https://www.linkedin.com/in/janedoe"
    }
  ]
}

Enrichment Status

Poll the status of a Cleanlist bulk enrichment workflow. Call repeatedly until status is "completed", "completed_with_errors", or "failed" — then read the results array. Recommended poll interval: every 5–10 seconds.

Operation Type: Query (Read)

Parameters:

• workflow_id string (required): Workflow ID returned by cleanlist/enrich/bulk

Returns:

• workflow object:
  • workflow_id string: Workflow identifier
  • status string: "queued", "running", "completed", "completed_with_errors", or "failed"
  • enrichment_type string (nullable): Enrichment type the workflow was submitted with
  • summary object (nullable): Counts (null while running)
    • total number (nullable): Total records submitted
    • successful number (nullable): Successfully enriched
    • failed number (nullable): Failed to enrich
    • emails_found number (nullable): Records that yielded an email
    • phones_found number (nullable): Records that yielded a phone
  • results array of objects (nullable): Enriched records (null while running). Each result includes task_id, primary_email, primary_email_status, prospect, company, etc.
  • completed_at string (nullable): ISO-8601 completion timestamp

Example Usage:

{
  "workflow_id": "public_bulk_4d6f2c3a-1f8b-4c8d-a9e3-2c1b9f5a4d8b"
}

Account

Credit Balance

Check the current credit balance on your Cleanlist account. Use this before submitting a large bulk enrichment to confirm you have enough credits.

Operation Type: Query (Read)

Parameters:

• None.

Returns:

• Current account balance details (credit count and any plan metadata Cleanlist returns).

Example Usage:

{}

Common Use Cases

Outbound Prospecting:

• Enrich a list of names + companies pulled from LinkedIn or a CRM export
• Get verified work emails and direct phones for cold outreach
• Validate an existing list before launching a sequence

Data Hygiene:

• Bulk-validate emails on inactive CRM contacts and re-engage the ones that bounce
• Refresh stale job-title and employer fields on accounts you haven't touched in months
• Standardize LinkedIn URLs into contact records

Lead Workflows:

• Trigger Cleanlist whenever a new prospect signs up — append email, phone, and firmographic context before routing to a rep
• Score inbound leads using successful / emails_found counts as a data-quality signal
• Auto-pause a workflow if the credit balance dips below a threshold