lead-lists

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.