Hunter

Use this when the user wants to create a new company list. Provide a `name`. By default the list is `static` (the user adds companies to it themselves). To create a `dynamic` list that automatically collects companies matching saved criteria, set `type` to `dynamic` and supply `filters` (a set of key/value criteria). Optionally place the list inside a folder with `company_list_folder_id`. Returns an invalid_input error (id validation_failed) if the name is missing, is already used by another list in the user's team, or a dynamic list is created without valid filters. Free to call.

Use this when the user wants to create a new company-list folder. Provide a `name` and a `color`. `color` must be one of the allowed Hunter folder colors (hex without a leading '#'): 374151, 3489F9, 10B981, F5BA0B, EF4444, 7C3AED, F97316, E5E7EB, B4D9F7, BAE6B0, FDE68A, FBD0D0, D4C4F8, FFD79B. Returns an invalid_input error (id validation_failed) if the name is missing or already used by another folder in the user's team, or if the color is missing or not one of the allowed values. Free to call.

Use this when the user wants to define a new custom attribute on leads, identified by label. Free to call.

Use this when the user wants to create a new lead in their Hunter account. Email is required; other fields are optional. Pass `leads_list_id` to add the lead directly to a list. Free to call. If a lead with this email already exists, the call succeeds and returns that lead, but does not apply the supplied values, including `custom_attributes`. It only adds the lead to `leads_list_id` when you pass one. To change the values of an existing lead, use Update-Lead or Create-Or-Update-Lead.

Use this when the user wants to save a verified contact as a new lead without modifying any existing lead. If a lead with the email already exists, returns it with `alreadyExisted: true` and never applies the supplied values to it; otherwise creates the lead with the supplied fields. Custom attribute values apply only when this tool creates the lead. An existing lead in no list (for example, one the team's automatic lead saving stored when Email-Verifier ran) is added to `leads_list_id` when you pass one, and Hunter can then refresh its fields from Hunter's own data, as for any lead saved in Hunter. A lead already in a list is never moved, added to another list, or changed. Use Create-Or-Update-Lead instead when the user explicitly wants to overwrite an existing lead. Free (no credits).

Use this when the user wants to create a new lead tag. Before creating one, call List-Lead-Tags and prefer reusing an existing tag with the same meaning (e.g. "Customers" vs "customer") instead of creating a near-duplicate — Add-Tag-To-Lead can also create a tag on the fly by name while tagging. Provide a `name`; `color` is optional and must be one of the allowed Hunter tag colors (hex without a leading '#'): 374151, 3489F9, 10B981, F5BA0B, EF4444, 7C3AED, F97316, E5E7EB, B4D9F7, BAE6B0, FDE68A, FBD0D0, D4C4F8, FFD79B — when omitted, Hunter picks a random color from that palette. Tags are shared with the whole team. Returns an invalid_input error (id validation_failed) if the name is missing, longer than 255 characters, or already used by another lead tag in the user's team. Free to call.

Use this when the user wants to create a new leads list with the given name. By default the list is static and empty: it keeps the leads the user adds to it. Use `type` `dynamic` with `filters` when the user wants a list that updates itself (a segment): it holds every lead that matches the filters, also leads saved later, and a lead that stops matching leaves it. Leads can't be added to a dynamic list or removed from it by hand. A filter with the same name as a List-Leads filter works the same way. `leads_count` in the result is the number of leads that match. Optionally place the list inside a folder with `leads_list_folder_id` (see List-Leads-List-Folders). Returns an invalid_input error if the folder does not belong to the user's team, if a filter is not supported, if `filters` is empty, or if `leads_list_id` is a dynamic list. Free to call.

Use this when the user wants to create a new leads-list folder to group leads lists — worth suggesting once the account has many lists. Provide a `name`; `color` is optional and must be one of the allowed Hunter folder colors (hex without a leading '#'): 374151, 3489F9, 10B981, F5BA0B, EF4444, 7C3AED, F97316, E5E7EB, B4D9F7, BAE6B0, FDE68A, FBD0D0, D4C4F8, FFD79B — when omitted, Hunter picks a random color from that palette. A team can have at most 100 folders. Returns an invalid_input error (id validation_failed) if the name is missing or already used by another folder in the user's team, if the color is not one of the allowed values, or if the folder limit is reached. Free to call.

Use this when the user wants to save a reusable message template — including when they ask to save a message draft written in chat (e.g. a sequence introduction or follow-up they liked) as a new template for later reuse. `name` and `body` are required; `subject` is optional and `message_format` defaults to html. The saved template can then pre-fill sequence steps via Create-Sequence-Follow-Up's `message_template_id`. Personalization placeholders like {{first_name}} are supported in the subject and body, and a fallback goes after a colon: {{first_name:"there"}}. The colon is the only separator that works — everything before it is read as the attribute name, so a piped form like {{first_name|fallback:"there"}} silently renders as an empty string. Placeholders carrying the literal fallback markers FALLBACK or DEFAULT are rejected with a validation error. Free to call.

Use this when the user explicitly wants to create a lead or overwrite an existing lead's fields by email. If a lead with the email exists, its fields are overwritten with the supplied values; otherwise a new lead is created. On an existing lead, `custom_attributes` merges into the current values: a slug that you leave out keeps its value, and an empty string clears the value. Free to call. Overwriting an existing lead's fields cannot be undone from the API. For save-without-overwrite semantics, use Create-Lead-If-Missing instead.

Use this when the user wants to save the current Discover filter set under a name so the search can be rerun later. Stores the `filters` payload verbatim and returns the created saved search; it also appears on the hunter.io Discover page. Names must be unique among the user's saved Discover searches — a duplicate name returns a validation error. There is no update endpoint: to change a saved search, delete it with Delete-Saved-Search and recreate it. Free to call.

Use this when the user wants to create a new outreach sequence. Only `name` is required; the sequence is created as a DRAFT that sends nothing until it is started. Lifecycle: draft → started (Start-Sequence) → paused/archived — the schedule and sender fields lock once started, so configure them while drafting. Optional fields: sender `email_account_ids` (connected email accounts — see List-Email-Accounts; unknown ids are rejected with unknown_email_account_ids), `schedule_days` (0=Monday..6=Sunday; a Monday-Friday schedule is [0, 1, 2, 3, 4], not [1, 2, 3, 4, 5]), the daily sending window `schedule_time_start`/`schedule_time_end` (seconds since midnight, start before end), a `start_at` date (YYYY-MM-DD, not in the past), `bcc_recipient`, tracking toggles (`tracked_links` requires a premium plan), and `add_unsubscribe_link` (false by default on a sequence created here) with its wording, `unsubscribe_sentence` for HTML emails (the link text goes between {{link}} and {{/link}}) and `unsubscribe_sentence_plain_text`. The introduction email (step 0) is created automatically with an empty subject and body, and Start-Sequence fails validation while it is blank — fill it in with Update-Sequence-Follow-Up, targeting the step whose `step` is 0 (get its id from List-Sequence-Follow-Ups). Typical next steps: write the introduction email with Update-Sequence-Follow-Up, append any further steps with Create-Sequence-Follow-Up, add recipients with Add-Sequence-Recipients, then launch with Start-Sequence (a connected email account, subject, and message body are required to start). Given a sending account that is already connected, the whole sequence can be built this way without opening the Hunter dashboard. Connecting a sending inbox is the one step that still needs the dashboard — the API only attaches an ALREADY-connected account, and email-account settings are read-only here. Free to call.

Use this when the user wants to add an email step to a sequence, or to A/B test an existing step with a Variant B. Author the sequence step-by-step in conversation: draft the `subject` and `body` with the user, set `wait_days` (days after the previous step, 0-999), create the step, then show the updated step list with List-Sequence-Follow-Ups. Also offer the team's saved templates (List-Message-Templates): passing `message_template_id` pre-fills whichever of `subject`, `body`, and `message_format` are left blank. Without `variant`, the step number is assigned automatically after the current last step, so a plain create always appends a new follow-up and never reaches an existing step — to author the introduction email (step 0), or to rewrite any existing step, use Update-Sequence-Follow-Up instead. Omitting `subject` makes the step inherit the previous step's subject so the emails thread together. A sequence holds at most 6 steps in total (the introduction plus up to 5 follow-ups); exceeding that, or adding to an actively sending sequence (pause it first) or an archived one, is rejected with an invalid_input error. To A/B test a step, pass `variant: "B"` with that step's `step` number (step 0 included): this adds Variant B to the existing step, and the step itself becomes Variant A. Send the B copy in `body`, `subject`, or both: omitted `subject`, `body`, `wait_days`, and `message_format` are copied from Variant A, so a subject-line test sends only `subject`. Hunter refuses a Variant B whose subject and body both match Variant A (invalid_input). The first Variant B turns A/B testing on for the sequence, sets a 50/50 target split (recipients already sent an email stay on Variant A; only unsent recipients are split), and switches off the AI writing assistant. It needs A/B testing in the user's plan (error id ab_testing_requires_upgrade) and is rejected while the sequence is sending (sequence_active) or scheduled to start (sequence_planned). Edit either arm afterwards with Update-Sequence-Follow-Up, and read the test state from `ab_testing` in Get-Sequence. Changing the split, picking a winner, and removing Variant B are only possible in the Hunter dashboard. Hunter does not deduplicate this call. If it fails with "already has a Variant B" after a create whose response was lost or timed out, the earlier call succeeded. Confirm with List-Sequence-Follow-Ups and do not create it again. Free to call.

Use this when the user wants to delete a company list by ID. Empty lists and dynamic lists are deleted immediately (status 204). A static list that still contains companies is deleted asynchronously: a background job removes its companies and the call returns status 202 (accepted) right away. Deleting a list cannot be undone from the API. Returns a not-found error if the list does not exist or belongs to another team. Free to call.

Use this when the user wants to delete a company-list folder by ID. Deleting a folder does not delete the company lists filed in it — each affected list keeps existing and simply becomes unfiled (its folder is cleared). Deleting a folder cannot be undone from the API. Only the folder's owner, a team admin, or the team owner may delete it. Succeeds with no content on success. Returns a not-found error if the folder does not exist, or a forbidden error if the user is not allowed to delete it. Free to call.

Use this when the user wants to permanently delete a custom-attribute definition, identified by ID. Per-lead values stored for the attribute are dropped and cannot be recovered. Free to call.

Use this when the user wants to remove a lead from their Hunter account, identified by ID. Free to call. Deleting a lead cannot be undone from the API.

Use this when the user wants to delete a lead tag by ID. Deleting a tag removes it from EVERY lead it is applied to (the tag's assignments are destroyed with it); the leads themselves are untouched. This cannot be undone from the API, so confirm with the user before deleting a tag that may still be in use — to detach a tag from a single lead instead, use Remove-Tag-From-Lead. Only the tag's owner, a team admin, or the team owner may delete it. Succeeds with no content on success. Returns a not-found error if the tag does not exist or belongs to another team, or a forbidden error if the user is not allowed to delete it. Free to call.

Use this when the user wants to permanently delete a leads list, identified by ID. Lists with more than 10 leads are scheduled for asynchronous deletion (HTTP 202). Free to call. Deleting a list cannot be undone from the API.

Use this when the user wants to delete a leads-list folder by ID. Deleting a folder does not delete the leads lists filed in it — each affected list keeps existing and simply becomes unfiled (its folder is cleared and it is re-ordered after the existing unfiled lists). Deleting a folder cannot be undone from the API. Only the folder's owner, a team admin, or the team owner may delete it. Succeeds with no content on success. Returns a not-found error if the folder does not exist, or a forbidden error if the user is not allowed to delete it. Free to call.

Use this when the user wants to permanently delete a saved message template by ID. Deleting cannot be undone from the API. Sequence steps already created from this template keep their own copy of the subject and body, so deleting the template does not change any existing sequence. Returns a not-found error if the template does not exist or belongs to another team. Free to call.

Use this when the user wants to permanently delete a saved Discover search, identified by ID. Deletion cannot be undone through the API. Because saved searches have no update endpoint, delete-and-recreate is also how to change one: delete it, then call Create-Saved-Search with the new name or filters. Returns a not-found error if the saved search does not exist or belongs to another user. Free to call.

Use this when the user wants to permanently delete a DRAFT sequence. Deletion is drafts-only: a started or archived sequence cannot be deleted (invalid_input error, id sequence_not_destroyable) — archive a finished sequence instead. Deletion is permanent and cannot be undone; it removes the sequence together with its steps and staged recipients, so always confirm with the user first: the first call returns a confirmation prompt (mentioning how many recipients would be removed) WITHOUT deleting anything, and only re-issuing with `confirmed: true` actually deletes the sequence. Returns a not-found error if the sequence does not exist or belongs to another team. Free to call.

Use this when the user wants to remove a step from a sequence. Only the LAST step can be deleted — to redo an earlier step, delete steps from the end back down to it, then re-create them. Deletion is rejected with an invalid_input error when the step is the introduction (step 0 can never be deleted), is not the last step, already has sent messages, is part of an A/B test (disable A/B testing first), or when the sequence is actively sending (pause it first), scheduled to start, or archived. On success the step is permanently removed and an acknowledgement is returned. Returns a not-found error if the sequence or the step does not exist or belongs to another team. Free to call.

Use this when the user wants to know how many email addresses Hunter has for a company domain, optionally split by personal vs generic. Returns counts only, and a link to hunter.io where the user can see the addresses. Free to call.

Use this when the user wants to look up a company by domain and see its industry, size, location, technologies, funding rounds, and social profiles. Does not return personal data (PII). Costs 0.2 credit on plans with a shared credit pool (but needs at least 1 credit left to start), or 1 search on other plans, charged only when data is found. Do not use this for personal websites or webmail domains (gmail.com, yahoo.com, etc.) — there is no company behind those domains to enrich.

Company-Enrichment

Use this when the user wants to mark a company list as a favorite, identified by ID. Favoriting is a reversible flag (it can be undone later) and does not change the list's contents. The call is idempotent: favoriting a list that is already a favorite still succeeds and returns `favorited: true`. Surface the `favorited: true` response to confirm the action succeeded. Returns a not-found error if the list does not exist or belongs to another team. Free to call.

Use this when the user wants to mark a leads list as a favorite, identified by ID. Favorites are a personal flag for the current user, and a favorited list is a strong signal of their preferred working list — suggest it as the default destination when the user saves new leads without naming a list. Favoriting is reversible (it can be undone later) and does not change the list's contents. The call is idempotent: favoriting a list that is already a favorite still succeeds and returns `favorited: true`. Surface the `favorited: true` response to confirm the action succeeded. Returns a not-found error if the list does not exist or belongs to another team. Free to call.

Use this when the user wants to search for companies that match natural-language criteria such as location, industry, size, type, or technologies. Returns up to 100 matching companies per page; use `limit` and `offset` to paginate. Plans without Discover paging get only the first page. The response includes `meta.permalink` — a link to the same query on hunter.io that the user can open to view all results with the inferred filters applied. Free to call. Do not use this when the user has already named a specific company — call Company-Enrichment directly with that company's domain.

Use this when the user wants companies similar to a company list or to one company, ranked by `similarity_score` (0-100, higher is closer). Seed with exactly one of `company_list_id` (a static company list; List-Company-Lists shows each list's `type`) or `domain` (one company). `industry` and `size` are hard filters. `industry` must match a LinkedIn industry name exactly (case-insensitive), so reuse the `industry` values from earlier results. `country` is a ranking preference, not a filter: same-country companies rank higher, but other countries and companies with no known country can still appear, so check each result's `country` before telling the user that all results are in one country. There is no paging. An empty `data` array means the domain is not in Hunter's index, the list has no companies, nothing similar was found, or the `industry`/`size` filters removed every result; say which is likely instead of telling the user that nothing similar exists. A dynamic list returns an invalid_input error (field unsupported_list_type): suggest a static company list or a `domain` seed instead. This feature is not available on free plans. A feature_not_in_plan error means it is not available on the user's current Hunter plan: tell the user that and do not ask the user to reconnect. An unauthorized error means the Hunter account is not connected. To save results, call Save-Company for each company the user picks to get its company id. For one or two companies, then call Add-Company-To-List; for more, add all the ids in one Bulk-Copy-Companies call. A company that is already in the target list counts as saved (Add-Company-To-List returns `already_in_list: true`); continue with the next one. Free to call.

Use this when the user asks about their Hunter plan or remaining credits. Returns plan name and per-product credit balances (search, verification, enrichment). Does not return personal identifiers such as name, email, or team ID. Free to call.

Use this when the user wants the details of a single company list, identified by ID: its `name`, `type` (static or dynamic), `filters` (for dynamic lists), `company_list_folder_id`, `created_at`, and `companies_count` (the number of companies currently in the list). Returns a not-found error if the list does not exist or belongs to another team. Free to call.

Use this when the user wants the details of a single connected app, identified by ID, including its `attribute_mappings` — the list of `target_field` ↔ `source_field` pairs that map Hunter fields to the integration's fields. Present the mappings as a table or list. Also returns the `provider`, resolved `name`, `category`, `provider_email`, and `connected_at` / `updated_at` timestamps. Returns a not_found error if the app does not exist or belongs to a different team. Free to call.

Use this when the user wants to retrieve a single custom-attribute definition by ID. Free to call.

Use this when the user wants to see how a specific sending email account is set up — e.g. "how is alice@acme.com configured?" — as a pre-check before suggesting changes to its settings. On top of the List-Email-Accounts fields (email, first/last name, `sending_status`, `daily_limit`, `provider`), it reports the `sender_name` shown on outgoing emails, whether it is the `default_account`, the email `signature` (sanitized HTML, null when none is stored), the owner's `profile_picture_url`, the team's `custom_tracking_domain` (null unless a verified custom tracking domain is configured), the default `sending_schedule` (days of week, HH:MM start/end times, and time zone) a new sequence sending from this account would run on, and the `warmup` state (`enabled`, `status`, `end_date`). Email account settings can NOT be changed through this API — inspection is read-only and settings writes are not yet available — so suggest changes for the user to apply in the hunter.io dashboard rather than offering to apply them. Returns a not-found error if the email account does not exist or is not one the user can manage. Free to call.

Use this when the user wants to retrieve a single lead from their Hunter account by ID. Free to call.

Use this when the user wants to retrieve a single leads list (name, lead count, folder, timestamps) by ID. Free to call.

Use this when the user wants to inspect a single saved message template by ID — its full `subject`, `body`, and `message_format` — for example to preview it before reusing it in a sequence follow-up (via Create-Sequence-Follow-Up's `message_template_id`), or to copy and adapt its content. Returns a not-found error if the template does not exist or belongs to another team. Free to call.

Use this when the user wants the details of one saved Discover search, identified by ID — typically to rerun it. Read the stored `filters` payload and describe it back to the user as a natural-language `query` for Find-Companies or Count-Company-Emails; this is an approximate rerun, because those tools accept only a `query` (or exact `domains`) and cannot re-apply the stored structured filters (locations, industries, funding, technologies, include/exclude lists) verbatim. Present the reformulated query and let the user confirm or refine before running it. Returns a not-found error if the saved search does not exist or belongs to another user. Free to call.

Use this when the user wants to inspect one sequence's full configuration. Returns the lifecycle `status` (draft, planned, active, paused, completed, preparing, error, or archived) plus the raw `started`/`paused`/`archived` booleans, the `schedule` (start_at date, daily sending window as HH:MM strings, days of week as integers 0=Monday..6=Sunday), the `settings` (open tracking, link tracking, unsubscribe link, the HTML and plain-text unsubscribe sentences — null when the account default applies, AI assistant, BCC recipient), the sender `email_account_ids`, a `follow_ups` step summary (unique_steps_count and step numbers — use List-Sequence-Follow-Ups for the step contents), `recipients_count`, the `owner`, and the `ab_testing` state (`enabled`, the Variant A/B split percentages, and any `winner_variant`; every field but `enabled` is null when no A/B test is on). Returns a not-found error if the sequence does not exist or belongs to another team. Free to call.