How to connect Hunter.io with Python

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 `offset` to paginate. 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.

Use this when the user wants the contacts published for a domain — emails with names, positions, and confidence scores. Optional filters: type, seniority, department, required field. Uses Hunter credits: 1 credit per 10 emails returned (rounded up), charged only when emails are found. Do not use this for personal/webmail domains (gmail.com, yahoo.com, etc.) — results will be empty.

Use this when the user wants the contacts published for a domain but guaranteed non-inferred — this returns ONLY found (published) email addresses Hunter has seen on the public web, never pattern-generated or inferred ones. Same fields and filters as Domain-Search (type, seniority, department, required field). Uses Hunter credits: 1 credit per 10 emails returned (rounded up), charged only when emails are found. Do not use this for personal/webmail domains (gmail.com, yahoo.com, etc.) — results will be empty.

Use this when the user wants a specific person's email address at a company. Provide the person's full name and the company's domain. Uses Hunter credits, charged only when an email is found. Do not use this when the user already has the email and only wants to confirm it works — call Email-Verifier instead.

Use this when the user wants to check whether an email address is deliverable. Returns a status (valid, invalid, accept_all, etc.) and a confidence score. Uses Hunter credits, charged only for valid, invalid, or accept_all results. Do not use this on role/group addresses (info@, support@, etc.) — deliverability of role addresses is not meaningful and the result will typically be accept_all.

Use this when the user wants the count of email addresses Hunter has indexed for a domain, optionally split by personal vs generic. Free to call. Do not use this as a substitute for Domain-Search; this returns a count only, not the email list itself.

Use this when the user wants to look up a person by email address and see their name, job title, employer, location, phone number, and social profiles. Uses Hunter credits, charged only when data is found.

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). Uses Hunter credits, charged only when data is found.

Use this when the user provides an email address or LinkedIn handle and wants both the person's profile and their company's profile in a single response. Uses Hunter credits, charged only when data is found.

Use this when the user asks about their Hunter account, plan, team, or remaining credits. Returns plan name, team info, and per-product credit balances (search, verification, enrichment). Free to call.

List the email accounts (sending inboxes) connected to your Hunter account. This is the first step before creating or starting a sequence — every account reports a `sending_status` of `active` (ready to send), `paused` (disconnected, will not send until reconnected), or `warming` (in ramp-up or warmup, sending a reduced volume). Each entry also includes the sender's email, name, daily sending limit, and provider (such as gmail or outlook). Supports `limit` and `offset` pagination. Free (no credits).

Get the full configuration of one sending email account — the pre-check to run before suggesting changes to an account's 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 (no credits).

List the sequences that send from a given email account — the dependency check to run before pausing, reconfiguring, or disconnecting an account. Pairs with List-Email-Accounts (find the account and its id) and Get-Email-Account (inspect its configuration). Each entry reports the sequence `id`, `name`, `status` (draft, planned, active, paused, or archived), `recipients_allocated` (recipients assigned to this account within the sequence, canceled recipients excluded), and `emails_scheduled` (emails still waiting to be sent from this account), most recent first. Archived sequences are excluded by default; pass `include_archived: true` to include them. Supports `limit` and `offset` pagination. Returns a not-found error if the email account does not exist or is not one the user can manage. Free (no credits).

List the follow-up steps of a sequence, ordered by step. Step 0 is the introduction message and steps 1 and up are follow-ups; each step reports its `wait_days` (days to wait before sending), `subject` (the email subject; an inherited subject is resolved to the prior step's subject, so it is rarely empty), `body`, `message_format` (text or html), `messages_sent`, and `variant` (null, or A/B for A/B-tested steps). Supports `limit` and `offset` pagination. Returns 404 if the sequence does not exist or belongs to another team. Free (no credits).

Pause a started sequence so it stops sending outbound emails until it is resumed. Only a started, non-archived sequence can be paused: pausing a draft (not yet started) or an archived sequence returns an invalid_input error (id sequence_not_active). Pausing an already-paused sequence is idempotent and succeeds. Returns the sequence id and its paused state. Returns a not-found error if the sequence does not exist or belongs to another user (this endpoint is owner-only). Pausing is reversible — resume the sequence to continue sending. Free (no credits).

Resume a paused sequence so it starts sending outbound emails again. Resuming runs the full validation pipeline (unlike pausing), so it can fail with an invalid_input error: resuming an archived sequence is rejected (id sequence_not_active), and resuming a sequence whose email account is no longer connected or whose schedule has no sending days fails validation (id validation_failed, with a field-specific message). Resuming a sequence that is not currently paused is a no-op that succeeds with the message "Sequence is not paused.". On success the response carries a `message` describing the outcome. Returns a not-found error if the sequence does not exist or belongs to another user (this endpoint is owner-only). Resuming is reversible — pause the sequence to stop sending. Free (no credits).

Archive a started sequence to file it once it is finished. Only a started sequence (active or paused) can be archived: archiving a draft (a sequence that was never started) returns an invalid_input error (id sequence_not_started). Archiving an already-archived sequence is idempotent and succeeds. On success the response reports the sequence id and its archived state. Archiving stops the sequence from sending and cannot be undone through the API: an archived sequence cannot be resumed or un-archived via the API. Returns a not-found error if the sequence does not exist or belongs to another user (this endpoint is owner-only). Free (no credits).

Use this when the user wants to see how a sequence is performing. Reports recipient-based stats for a sequence plus a per-follow-up breakdown. The top-level engagement totals (`sent`, `delivered`, `opened`, `clicked`, `replied`, `unsubscribed_recipients`) count DISTINCT recipients — e.g. `replied` is the number of recipients who replied at least once, not the number of reply messages — and `delivered` is the recipients who received at least one non-bounced email (`recipients_count` is all recipients ever added to the sequence). `bounced` is message-based (a bounce is an SMTP-level event). The rate fields (`open_rate`, `click_rate`, `reply_rate`, `bounce_rate`, `unsubscribed_recipients_rate`) are floats in the 0.0-1.0 range — multiply by 100 to present them as percentages to the user — and are 0 when their denominator is 0; `open_rate`, `click_rate`, and `reply_rate` divide by distinct delivered recipients, while `bounce_rate` is message-based. The `follow_ups` array reports MESSAGE-based metrics per step (ordered by step, then variant; `variant` is null for the default follow-up or A/B for A/B-tested steps), so per-step counts do not sum to the recipient-based top-level totals. Returns a not-found error if the sequence does not exist or belongs to another team. Free to call.

List the sequences in your Hunter account with name, lifecycle booleans (started/archived/paused), recipient count, and owner, most recent first. Optionally filter by `started` and/or `archived` state and paginate with `limit`/`offset`. New sequences can be created with Create-Sequence and inspected in full with Get-Sequence. Free (no credits).

Get 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, 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`, and the `owner`. Returns a not-found error if the sequence does not exist or belongs to another team. Free (no credits).

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`, and tracking toggles (`tracked_links` requires a premium plan). 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 (no credits).

Update an existing sequence's name, schedule, senders, or settings; omitted fields are left unchanged. On a draft every field is editable. Once the sequence has STARTED or been ARCHIVED, the schedule and sender fields are locked: changing `schedule_time_start`, `schedule_time_end`, `schedule_days`, `start_at`, `email_account_ids`, `bcc_recipient`, `tracked`, or `tracked_links` is rejected with an invalid_input error (id sequence_locked) — only `name` and `add_unsubscribe_link` (a compliance lever) stay editable, and re-sending an unchanged value is tolerated. Other validation failures return field-specific errors (unknown_email_account_ids, invalid_schedule_days, invalid_schedule_window, start_at_in_the_past, tracked_links_requires_premium, ...). Returns the updated sequence. Returns a not-found error if the sequence does not exist or belongs to another team. Free (no credits).

Delete a DRAFT sequence permanently. 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 (no credits).

Get a single step of a sequence by its follow-up ID (from List-Sequence-Follow-Ups). Returns the step number (0 is the introduction email), `wait_days`, `subject`, `body`, `message_format` (text or html), `messages_sent`, and `variant` (null, or A/B for A/B-tested steps). Unlike List-Sequence-Follow-Ups, `subject` is returned raw: a step that inherits the previous step's subject shows an inheritance placeholder instead of the resolved text. Returns a not-found error if the sequence or the step does not exist or belongs to another team. Free (no credits).

Create a new email step in a sequence. 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. The step number is assigned automatically after the current last step, so this tool always appends a new follow-up and can never target step 0 — 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. Free (no credits).

Rewrite an existing step of a sequence — the only tool that can author the introduction email (step 0). Create-Sequence makes step 0 with an empty subject and body; fetch its id with List-Sequence-Follow-Ups, then set `subject` and `body` here — with a sending account already connected, that leaves nothing to do in the Hunter dashboard. Omitted fields are left unchanged on the step you target, with two documented side effects to relay to the user. First, changing a `subject` also rewrites the subject of every LATER step that still holds the old value verbatim (Hunter propagates a subject edit down the chain), and on a started sequence that regenerates the pending messages of the affected steps. This includes the ordinary build order: steps appended with no `subject` of their own are stored empty, so authoring step 0 afterwards propagates into every one of them. ALWAYS re-read the step list with List-Sequence-Follow-Ups after a subject change and tell the user which other steps moved. Second, setting `message_format` to text on a step that is currently html makes Hunter CONVERT the stored body even if you omit `body`: images are dropped, links collapse to bare URLs, and most HTML is stripped. That conversion is not reversible by setting the format back, so confirm it first, and show the user the converted `body` that comes back in the response. Editing is allowed on a draft or a paused sequence and is rejected with an invalid_input error while the sequence is actively sending (id sequence_active — pause it first), while it is scheduled to start (id sequence_planned), or once it is archived. `wait_days` accepts 0-999. Send 0 or omit it for step 0: the introduction always goes out first so the delay never delays anything, but a non-zero value still persists and inflates the delivery-time estimate Hunter shows for the sequence. CRITICAL — only pass `subject` when you are deliberately rewriting the subject line: never echo back a subject you just read from List-Sequence-Follow-Ups or Get-Sequence-Follow-Up while editing the body or the timing. On a step that inherits its subject from an earlier step, writing the value you read (the resolved text from the list, or the raw internal placeholder from the detail view) replaces the inheritance link with a fixed string and silently breaks subject threading for A/B recipients. Omit `subject` to keep inheriting. `body` must be non-blank when given. An empty-string `subject` is meaningful instead of invalid: on any step above 0 it RESTORES inheritance from the previous step, which is the only way to undo a concrete subject and re-thread the step. Never send an empty `subject` for step 0 — it has no previous step to inherit from, so it just clears the introduction subject and blocks Start-Sequence. Both fields are capped at 250 and 50000 characters respectively, because Hunter accepts a longer write and only rejects it at Start-Sequence. Note that Hunter normalizes a saved body even when you omit `body`: smart quotes are straightened and malformed links repaired. Merge fields must carry a fallback in the form {{first_name:"there"}}; a bare {{first_name}} or a pipe form like {{first_name|there}} is rejected or renders empty. Step 0 is created with `message_format` html, so send HTML in `body` or set `message_format` to text alongside a plain-text body. If the step you target has a non-null `variant` (an A/B test — visible in List-Sequence-Follow-Ups), this edits ONLY that arm; tell the user which arm changed. Requires that you own the sequence or are a team admin/owner. Returns the updated step. Returns a not-found error if the sequence or the step does not exist or belongs to another team. Free (no credits).

Delete 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 (no credits).

List recipients in a sequence. Free (no credits).

Add recipients to a sequence by email addresses or lead IDs. Max 50 per request — batch larger lists. For a draft sequence this only stages recipients and runs immediately; for an already-started sequence, adding a recipient immediately schedules a real outbound email to that recipient (no separate Start-Sequence call) and therefore requires explicit user confirmation: the first call returns a confirmation prompt without adding anyone, and only re-issuing with `confirmed: true` performs the add. Free (no credits).

Remove recipients from a sequence by email addresses. Pending (not-yet-sent) messages scheduled for the removed recipients are cancelled; messages already sent are not recalled. Free (no credits).

Use this when the user wants to start an existing sequence, which begins sending real emails to its recipients. The sequence must have a subject, message body, and connected email account configured. Free to call. Starting a sequence sends real emails to recipients and requires an explicit user confirmation: the first call returns a confirmation prompt without sending, and only re-issuing with `confirmed: true` actually starts the sequence.

List leads in your Hunter account with optional filters. Free (no credits). Returns up to 100 leads per page — use offset to paginate.

Get a single lead by ID. Free (no credits).

Create a new lead in your Hunter account. Free (no credits). Provide at least an email address. Use leads_list_id to add directly to a list.

Update an existing lead by ID. Free (no credits).

Delete a lead by ID. Free (no credits).

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. 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 a verified contact as a new lead without modifying any existing lead. If a lead with the email already exists, returns the existing record unchanged with `alreadyExisted: true` and reports "already exists; no changes made"; otherwise creates the lead with the supplied fields. Never overwrites, never moves to a list, never enriches existing records. Use Create-Or-Update-Lead instead when the user explicitly wants to overwrite an existing lead. Free (no credits).

Check if a lead with a given email address exists. Free (no credits).

Save a company as a lead in your Hunter account. Free (no credits).

List all leads lists in your Hunter account. Free (no credits).

Get a single leads list by ID. Free (no credits).

Create a new leads list. Free (no credits).

Rename an existing leads list. Overwrites the existing list name; the previous name cannot be recovered from the API. If the user declines the rename, offer to create a new leads list with the desired name instead. Free (no credits).

Delete a leads list by ID. Lists with more than 10 leads are deleted asynchronously (status 202). Free (no credits).

Merge one leads list into another. All leads from the source list are moved to the destination list, and the source list is deleted. Free (no credits).

List the company lists in your Hunter account, ordered with the most recently created first. Each list reports its `type` — `static` (a fixed set of companies you add manually) or `dynamic` (companies matched automatically by saved `filters`, which are included for dynamic lists) — along with its `name`, `company_list_folder_id` (the folder it lives in, or null), and `created_at`. Supports `limit` and `offset` pagination. Free (no credits).

Get a single company list by ID, including 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 (no credits).

Create a new company list. Provide a `name`. By default the list is `static` (you add companies to it yourself). 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 your team, or a dynamic list is created without valid filters. Free (no credits).

Update a company list, identified by ID. You can rename it (`name`), move it to a different folder (`company_list_folder_id`), and — for a dynamic list — change its `filters`. Renaming overwrites the previous name, which cannot be recovered from the API. Succeeds with no content on success. Returns a not-found error if the list does not exist or belongs to another team, or an invalid_input error (id validation_failed) if the new name is empty or the filters are invalid. Free (no credits).

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 (no credits).

List the company-list folders in your Hunter account, ordered with the most recently created first. Folders group company lists; each folder reports its `name`, `color` (a hex color string), `company_lists_count` (how many lists are filed in it), and `created_at`. Folders are visible to the whole team. Supports `limit` and `offset` pagination. Free (no credits).

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 your team, or if the color is missing or not one of the allowed values. Free (no credits).

Update a company-list folder, identified by ID. You can rename it (`name`) and change its `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. Renaming overwrites the previous name, which cannot be recovered from the API. Succeeds with no content on success. Only the folder's owner, a team admin, or the team owner may update it. Returns a not-found error if the folder does not exist, a forbidden error if you are not allowed to update it, or an invalid_input error (id validation_failed) if the new name is duplicated or the color is not one of the allowed values. Free (no credits).

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 you are not allowed to delete it. Free (no credits).

Mark a company list as a favorite, identified by ID. Favoriting is a reversible flag (you can unfavorite it later); it 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`. Returns a not-found error if the list does not exist or belongs to another team. Free (no credits).

Remove the favorite flag from a company list, identified by ID. This only clears the favorite marker; the list and its contents are untouched, and you can favorite it again later. The call is idempotent: unfavoriting a list that is not currently a favorite still succeeds and returns `favorited: false`. Returns a not-found error if the list does not exist or belongs to another team. Free (no credits).

Add a company to a static company list (save the company to the list). Identify the list by `company_list_id` and the company by `company_id` (a company already saved in your account). Both the list and the company must belong to your team, and the list must be static — dynamic lists collect companies automatically by their filters and cannot have companies added manually. Returns the added company (`id`, `domain`, `created_at`). Returns an invalid_input error (id validation_failed) if the company is already in the list, a not-found error if the list or company does not exist, belongs to another team, or the list is dynamic, or a forbidden error if you are not allowed to modify this list. Free (no credits).

Remove a company from a static company list. Identify the list by `company_list_id` and the company by `company_id`. This removes only the membership link between the company and the list; the company itself is not deleted and can be added back to the list later, so the action is reversible. The list must be static (dynamic lists manage their members automatically). Succeeds with no content on success. Returns a not-found error if the list or company does not exist, belongs to another team, the list is dynamic, or the company is not in the list, or a forbidden error if you are not allowed to modify this list. Free (no credits).

List the connected apps (third-party integrations such as HubSpot, Pipedrive, Google Sheets, or a custom SMTP/IMAP inbox) linked to your Hunter account. Each entry includes the `provider` and a resolved `name` (canonical names like Google Sheets come from Hunter's internal catalog; others fall back to the provider name), plus `category`, `provider_email`, and the `connected_at` / `updated_at` timestamps. Supports `limit` and `offset` pagination. Returns an empty list if no apps are connected. Free (no credits).

Get a single connected app by ID, including its `attribute_mappings` — the list of `target_field` ↔ `source_field` pairs that map Hunter fields to the integration's fields. 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 (no credits).

List all custom attributes for leads. Free (no credits).

Get a single custom attribute by ID. Free (no credits).

Create a new custom attribute for leads. Free (no credits).

Rename an existing custom attribute. Overwrites the existing label everywhere the attribute is used; the previous label cannot be recovered from the API. If the user declines the rename, offer to create a new custom attribute with the desired label instead. Free (no credits).

Delete a custom attribute by ID. Free (no credits).

List the saved message templates in the user's Hunter account. When the user is drafting a sequence step (an introduction message or a follow-up), list the templates first and ask whether they want to use a saved template as the starting point. Each template carries a reusable `subject`, `body`, and `message_format` (text or html). To build a follow-up step from one, pass the chosen template's id as `message_template_id` to Create-Sequence-Follow-Up: the step's subject, body, and format are pre-filled from the template (any subject/body passed explicitly wins over the template's). Supports `limit` and `offset` pagination (default 25 per page, max 100); templates are ordered newest first. Free (no credits).

Retrieve 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 (no credits).

Create a reusable message template — including saving a message draft written in chat (e.g. a sequence introduction or follow-up the user 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 (no credits).

Update a saved message template's name, subject, body, or message format. Only the fields provided are changed; the previous values are overwritten and cannot be recovered from the API. Sequence steps already created from this template keep their own copy of the subject and body, so updating 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 (no credits).

Delete a saved message template by ID. Deleting is permanent and 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 (no credits).

List the lead tags in your Hunter account — call this BEFORE tagging leads or creating a new tag, so an existing tag can be reused instead of creating a near-duplicate. Tags label leads for organization and filtering and are shared with the whole team. Tags are ordered with the most recently created first; each tag reports its `name`, `color` (a hex color string), and `created_at`. Supports `limit` and `offset` pagination (default limit 25, max 100). Free (no credits).

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 your team. Free (no credits).

Update a lead tag, identified by ID: rename it (`name`) or change its `color`. Renaming overwrites the previous name everywhere the tag is applied, and the old name cannot be recovered from the API. `color` 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. Returns the updated tag. Only the tag's owner, a team admin, or the team owner may update it. Returns a not-found error if the tag does not exist or belongs to another team, a forbidden error if you are not allowed to update it, or an invalid_input error (id validation_failed) if the new name is empty, too long, or duplicated, or the color is not one of the allowed values. Free (no credits).

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 — 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 you are not allowed to delete it. Free (no credits).

Add a tag to a lead, identified by `lead_id`. Provide either `tag_id` (an existing tag) or `tag_name`; with `tag_name`, a tag that does not exist yet is created automatically with a random color. Call List-Lead-Tags first and reuse an existing tag (by `tag_id` or its exact name) before introducing a near-duplicate name. The call is idempotent: re-adding a tag the lead already has still succeeds. Returns the lead's full current tag set (`tags`, each with `id`, `name`, and `color`). Returns an invalid_input error (id tag_required) if neither `tag_id` nor `tag_name` is given, a not-found error if the lead or the tag does not exist or belongs to another team, or an invalid_input error (id validation_failed) if the new tag name is invalid. Free (no credits).

Remove a tag from a single lead, identified by `lead_id` and `tag_id`. This only detaches the tag from that lead; the tag itself is not deleted and stays available to re-apply later, so the action is reversible (to delete the tag everywhere, use Delete-Lead-Tag). The call is idempotent: removing a tag the lead does not have still succeeds. Succeeds with no content on success. Returns a not-found error if the lead or the tag does not exist or belongs to another team. Free (no credits).

List the leads-list folders in your Hunter account, ordered with the most recently created first. Folders group leads lists and are visible to the whole team — surface them when the account has many lists, since grouping lists by folder is how users keep a large workspace navigable. Each folder reports its `name`, `color` (a hex color string), `leads_lists_count` (how many lists are filed in it), and `created_at`. Supports `limit` and `offset` pagination (default 20, max 100). Free (no credits).

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 your team, if the color is not one of the allowed values, or if the folder limit is reached. Free (no credits).

Update a leads-list folder, identified by ID. You can rename it (`name`) and change its `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. Renaming overwrites the previous name, which cannot be recovered from the API. Succeeds with no content on success. Only the folder's owner, a team admin, or the team owner may update it. Returns a not-found error if the folder does not exist, a forbidden error if you are not allowed to update it, or an invalid_input error (id validation_failed) if the new name is duplicated or the color is not one of the allowed values. Free (no credits).

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 you are not allowed to delete it. Free (no credits).

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 saving new leads without a named list. Favoriting is reversible (you can unfavorite it 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`. Returns a not-found error if the list does not exist or belongs to another team. Free (no credits).

Remove the favorite flag from a leads list, identified by ID. This only clears the current user's personal favorite marker; the list and its contents are untouched, and you can favorite it again later. The call is idempotent: unfavoriting a list that is not currently a favorite still succeeds and returns `favorited: false`. Returns a not-found error if the list does not exist or belongs to another team. Free (no credits).

Move many leads at once from one static leads list to another. Both lists must be static (not dynamic) and different; `lead_ids` optionally narrows the move to specific leads inside the source list, otherwise every lead in the source list is moved. The move runs asynchronously — the response reports the matched `leads_count` with status `queued`. Returns a not-found error if either list does not exist in the team and an invalid_input error if a list is dynamic or no leads match the selection. Requires explicit user confirmation: the first call returns a confirmation prompt stating the affected count without moving anything, and only re-issuing with `confirmed: true` performs the move. Free (no credits).

Delete many leads at once, selected by explicit `lead_ids` and/or by a whole `leads_list_id`. Deleting leads is permanent and cannot be undone. Selections of 10 or fewer leads are deleted synchronously and the response reports the exact `deleted_count` with status `completed`; larger selections are queued for asynchronous deletion (status `queued` with the matched `requested_count`). Returns a not-found error if the leads list does not exist in the team and an invalid_input error when no leads match the selection. Requires explicit user confirmation: the first call returns a confirmation prompt stating the affected count without deleting anything, and only re-issuing with `confirmed: true` performs the deletion. Free (no credits).

Move many companies at once from one static company list to another. Both lists must be static (not dynamic) and different; `company_ids` optionally narrows the move to specific companies inside the source list, otherwise every company in the source list is moved. The move runs asynchronously — the response reports the matched `companies_count` with status `queued`. Both lists are modified, so a regular team member must own them (otherwise a forbidden error). Returns a not-found error if either list does not exist in the team and an invalid_input error if a list is dynamic or no companies match the selection. Requires explicit user confirmation: the first call returns a confirmation prompt stating the affected count without moving anything, and only re-issuing with `confirmed: true` performs the move. Free (no credits).

Copy many companies at once into a static company list, leaving the source selection untouched. Select the companies by explicit `company_ids` and/or by a source `company_list_id` (at least one is required); `target_company_list_id` is the static destination list. The copy runs asynchronously — the response reports the matched `companies_count` with status `queued`. The destination is modified, so a regular team member must own it (otherwise a forbidden error). Returns a not-found error if a list does not exist in the team and an invalid_input error if the destination is dynamic or no companies match the selection. Requires explicit user confirmation: the first call returns a confirmation prompt stating the affected count without copying anything, and only re-issuing with `confirmed: true` performs the copy. Free (no credits).

Delete many companies at once, selected by explicit `company_ids` and/or by a whole `company_list_id`. Deleting companies is permanent and cannot be undone; a regular team member only deletes their own companies. Selections of 10 or fewer companies are deleted synchronously and the response reports the exact `deleted_count` with status `completed`; larger selections are queued for asynchronous deletion (status `queued` with the matched `requested_count`). Returns a not-found error if the company list does not exist in the team and an invalid_input error when no companies match the selection. Requires explicit user confirmation: the first call returns a confirmation prompt stating the affected count without deleting anything, and only re-issuing with `confirmed: true` performs the deletion. Free (no credits).

Count the people that can be extracted from companies — the bridge from Find-Companies to actual contacts; call it right after a Find-Companies result when the user says 'now get me the people at these companies'. For each matching company it reports how many email addresses Hunter's public index holds: `emails_count.personal` counts addresses tied to a named person (the people you can actually extract), `emails_count.generic` counts role-based addresses such as info@ or sales@, and `emails_count.total` combines both. `meta.total_emails` aggregates the same three counters across ALL companies matching the search — not just the current page — so use it to size a prospecting batch upfront. This tool returns counts only, from Hunter's public index: to reveal the actual email addresses, names, and positions at a company, call Domain-Search with that company's domain (uses credits). Provide either `query` (natural-language criteria, translated to filters exactly like Find-Companies) or `domains` (exact company domains, e.g. lifted from a Find-Companies result); when both are given, `query` takes precedence and `domains` is not sent. Free (no credits).

List the Discover searches saved in your Hunter account — a good opening move at the start of a prospecting conversation ('want to rerun one of your saved searches?'). Each saved search carries its `id`, `name`, the stored `filters` payload, and timestamps, ordered newest first. To rerun one, read its `filters` and `name` and describe them to the user as a natural-language `query` for Find-Companies or Find-People — that reformulation is approximate, since these tools take only a `query` (or exact `domains`) and cannot re-apply the stored structured filters (locations, industries, funding, technologies, include/exclude lists) verbatim. Supports `limit` and `offset` pagination (`meta.total` is the full count). Free (no credits).

Get one saved Discover search 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 Find-People; 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 (no credits).

Create a saved Discover search: store the current 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 your 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 (no credits).

Delete a saved Discover search by ID, permanently. 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 (no credits).

Push Hunter leads into the CRM behind a connected app (lead-syncing providers: HubSpot, Pipedrive, Salesforce, Zapier, and Zoho). List targets with List-Connected-Apps first. Select the leads with EITHER `lead_ids` (specific leads) OR `leads_list_id` (every lead in that list); when both are provided the list takes precedence. The push is asynchronous: success only means the job was queued (`status: "queued"` plus the matched `leads_count`) — tell the user to check their CRM shortly for the synced leads. Returns a not-found error for an unknown connected app or leads list, and an invalid_input error when the app does not support lead syncing or no leads match the selection. Pushing writes lead data into the user's external CRM and requires an explicit user confirmation: the first call returns a confirmation prompt without pushing; only re-issuing with `confirmed: true` actually queues the push. Free (no credits).

List the webhooks configured on the Hunter account — useful for integration debugging: is my webhook configured, which event does it listen to, and where does it deliver? Each webhook reports its `id`, `target_url` (the endpoint Hunter POSTs the event payload to), and `event` — one of lead.created, message.sent, message.read, message.clicked, message.replied, export.completed, import.completed, sequence.paused, or sequence.resumed. Results are ordered newest first and support `limit` and `offset` pagination (`meta.total` carries the overall count). Returns an empty list when no webhooks are configured. Free (no credits).

Update an existing webhook, re-pointing it to a different `target_url` (the endpoint Hunter POSTs to) and/or subscribing it to a different `event` (one of lead.created, message.sent, message.read, message.clicked, message.replied, export.completed, import.completed, sequence.paused, or sequence.resumed). This OVERWRITES configuration another system may already rely on: an integration listening on the old URL or event stops receiving deliveries immediately, so review the webhook with List-Webhooks first and make sure the user really wants to change it. Provide at least one of `target_url` or `event` — a call with neither returns an invalid_input error without contacting the API. Returns the updated webhook. Fails with an invalid_input error when the new `target_url` is not a valid 12-500 character HTTP(S) URL or the `event` is not supported, and a not-found error if the webhook does not exist or is not visible to the account. Free (no credits).

Report the team's quota usage for the current billing period. Call this proactively BEFORE any large credit-consuming action (a Domain-Search loop over many companies, bulk email verification, bulk enrichment) and warn the user when the planned work would exceed the remaining quota. Reports per-bucket usage — `searches` and `verifications`, plus a `credits` summary on plans with a single credits bucket — each with `used`, `available`, and `remaining`, and `reset_date` (the day the quota resets, i.e. the end of the current billing period). Reading usage consumes no credits and no requests. Free (no credits).

List the Hunter API keys of the connected user. Keys are scoped to the requesting user, not the team — another team member's keys are never visible here. Key values are masked (only the last 4 characters are shown, e.g. `********abcd`); the full value of a key is visible only once, in the Create-API-Key response. Managing keys requires connecting with an API key: connections authorized via OAuth get an unauthorized error ("API keys can't be managed with an OAuth token. Use your API key instead.") — relay that message to the user instead of retrying. Supports `limit` and `offset` pagination. Free (no credits).

Create a new Hunter API key for the connected user, optionally with a name (names must be unique among the user's keys; a user can have at most 100 keys). SECURITY: this tool's response is the ONLY time the full key value is ever visible — every later listing shows it masked. Treat it as a secret: surface it to the user once so they can save it, never repeat it back into the conversation more than once, and never write it into leads, notes, or other tools. Managing keys requires connecting with an API key: connections authorized via OAuth get an unauthorized error — relay it to the user instead of retrying. Creating a key requires explicit user confirmation: the first call returns a confirmation prompt without creating anything, and only re-issuing with `confirmed: true` creates the key. Free (no credits).

Delete one of the connected user's Hunter API keys by ID, permanently. Deletion is immediate and irreversible: anything still authenticating with the key — scripts, integrations, connected tools, possibly this very connection — stops working the moment it is deleted. The server refuses to delete the user's LAST remaining key (a user must always keep at least one; that request fails with a validation error). Keys are scoped to the requesting user: a key belonging to someone else returns a not-found error. Managing keys requires connecting with an API key: connections authorized via OAuth get an unauthorized error — relay it to the user instead of retrying. Deleting requires explicit user confirmation: the first call returns a confirmation prompt without deleting, and only re-issuing with `confirmed: true` deletes the key. Free (no credits).

Use this when the user gives a natural-language prospecting brief (e.g. "Find 20 marketing leads at fintech companies in Berlin") and wants a step-by-step plan for finding companies and their contacts. Returns the plan plus a first action so the model can execute the chain end to end. By default it gathers contacts for review and returns them as a table; it only saves to the user's Hunter leads when the user explicitly asks. Free to call; sub-tools charge their own credits.

Report any problem you hit while using Hunter's API or tools — use this PROACTIVELY and liberally. Call it whenever: a tool or endpoint you expected doesn't exist, an input or its documentation was missing or misleading, a response errored or didn't match its documented shape, returned data looked wrong or incomplete, or a workflow was confusing or harder than it should be. Reporting is FREE, never consumes credits, and never blocks the user — you do not need to ask the user for permission. When in doubt, report. Always include the endpoint or tool name and concrete expected-vs-actual details so the Hunter team can act on it.