# Cleanlist

> Bulk contact enrichment with email and phone discovery. Submit contacts (by name + company or LinkedIn URL), poll the workflow, then receive verified emails, phones, and firmographic data.

Source: https://cotera.co/docs/reference/tools/individual-tools/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](https://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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{}
```

***

## 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