---
name: lead-lists
description: Creates and organizes Hunter leads lists — build a list from contacts or a search, populate it, merge lists, favorite them, and group them into folders. Use when the user wants to build a lead list, save search results to Hunter, organize contacts into lists, or tidy up their lists and folders.
user-invocable: true
argument-hint: Create a list of marketing leads from SaaS companies
---

# Lead Lists

Create leads lists, populate them with contacts, and organize them into folders.

## Examples

- `/hunter:lead-lists Create a list of marketing leads from SaaS companies`
- `"Save these contacts to a new list called Q2 Outreach"`
- `"Build a list from the domain search results"`
- `"Merge my two fintech lists"`
- `"Favorite my Q2 Outreach list"`

## Workflow

### Step 1: Determine the source

- **From a previous search** — use contacts already found via Domain Search. (Discover returns companies/counts, not contacts with emails, so route Discover results through Domain Search first to get saveable contacts.)
- **From specific emails/contacts** — the user provides addresses directly.
- **From a new search** — run the discover / domain-search skills first, then save results.

### Step 2: Create or pick the list

To reuse an existing list, `List-Leads-Lists` to browse and `Get-Leads-List` to read one. For a new list, call `Create-Leads-List` with a descriptive name. If the user gives none, suggest one from context (e.g., "Fintech CTOs - France - 2026-07-16").

Present the deep-link: "List created: https://hunter.io/leads?leads_list_id={id}"

### Step 3: Add leads

For each contact, call `Create-Lead-If-Missing` with the contact's data and the new `leads_list_id` — it adds new leads but never overwrites an existing lead's fields, so sparse search data can't clobber contacts the user already maintains. Note: for an email that is **already** a lead, `Create-Lead-If-Missing` returns the existing record unchanged and does **not** add it to the new list — report those as already-existing / not added rather than counting them as added. (`Create-Or-Update-Lead` *would* add them to the list but overwrites their fields; use it only when the user explicitly wants that.) `Lead-Exists` checks first if unsure. Include all available fields (`email`, `first_name`, `last_name`, `position`, `company`, `linkedin_url`). Report progress ("Adding lead 5 of 20…").

### Step 4: Organize

- **Merge** two lists → `Merge-Leads-Lists` (destructive — it moves all leads to the destination and permanently deletes the source list; confirm first, see Guardrails). Both lists must be **static** and the source non-empty — dynamic/saved lists are rejected.
- **Favorite / unfavorite** → `Favorite-Leads-List` / `Unfavorite-Leads-List`.
- **Folders** → `List-Leads-List-Folders`, `Create-Leads-List-Folder`, `Update-Leads-List-Folder` (create and rename folders). Note: the API has no way to move an existing list into a folder — that's a Hunter-dashboard action.
- **Rename** a list → `Update-Leads-List` (accepts the list `id` and a new `name` only).

### Step 5: Present summary

```
# List Created: [List Name]

**Leads added:** [count] | **Duplicates skipped:** [count]

View in Hunter: https://hunter.io/leads?leads_list_id={id}

## Next Steps
1. Add more leads to this list
2. Add these leads to a sequence (build-sequences skill)
3. Push the list to your CRM (push-to-crm skill)
4. Search for more contacts (discover / domain-search skills)
```

## Guardrails

Confirm before destructive actions — state what will be affected, then wait for a "yes":

- `Delete-Leads-List` — "This deletes the '[name]' list (the leads themselves stay in your account); if it's a static list that a dynamic/saved list depends on, those dependent lists are deleted too. Confirm?"
- `Merge-Leads-Lists` — moving leads permanently deletes the source list and can't be undone: "This merges '[source]' into '[dest]' and deletes '[source]'. Confirm?"
- `Delete-Leads-List-Folder` — clarify whether lists inside move out or are affected, and confirm.

## Credit Cost

Free — `Create-Leads-List`, `Create-Lead-If-Missing`, merges, and folder operations do not consume credits. Only the initial search (Domain Search, Email Finder) uses credits if leads come from a new search.

## Important Notes

- Use `Create-Lead-If-Missing` when saving search results so you never overwrite an existing lead; reserve `Create-Or-Update-Lead` for when the user intends to update existing leads.
- Lists can be merged later with `Merge-Leads-Lists` — but the merge deletes the source list, so confirm first.
- `List-Leads` returns up to 100 leads per page — use `offset` to paginate through larger lists.