Hunter.io API Documentation: A Complete Guide for Developers

What Most Guides Get Wrong About the Hunter.io API

Most tutorials frame the Hunter.io API as a simple tool to find email addresses. This is the first and most costly mistake. The API’s primary value isn’t just finding data; it’s about adding a layer of verification and confidence to your entire outreach process.

Treating it like a digital phonebook leads to disaster. One B2B startup I advised did just that. They used the Domain Search endpoint to pull 50,000 emails, loaded them into their outreach tool, and hit send. The result was a 32% bounce rate, which got their domain blacklisted by two major email providers within 48 hours, costing them an estimated $10,000 in lost sales opportunities while they scrambled to fix their sender reputation.

The second flawed assumption is that more API calls equal more value. Developers new to the API often build integrations that hammer the endpoints for every single lookup, every single time. This approach ignores the two most important features for cost control and performance: caching and bulk processing.

A common failure pattern is re-verifying the same corporate domains repeatedly in a CRM integration. A marketing agency burned through their $499/month “Enterprise” plan in just 12 days because their HubSpot integration called the Domain Search endpoint every time a contact’s record was updated. A simple 24-hour cache on verified domains would have reduced their call volume by over 60%, saving them nearly $300 a month.

Finally, many developers treat the API key as a simple password. It’s not. Think of it as a reputation token. Every call you make is tied to that key, and Hunter’s systems monitor its usage patterns for abuse.

Aggressive, un-throttled requests from a single key look like a potential attack, not a legitimate integration. This is why simply looping through a list and firing off requests as fast as possible is a surefire way to get a 429 “Too Many Requests” error, and eventually, a temporary suspension. Your API key’s health is directly tied to your application’s stability.

Avoiding these common traps requires a completely different mental model for how the API actually creates business value. With that in mind, let’s build a more effective framework for using it.

How the Hunter.io API Actually Works: A Value-Centric Framework

Building on the mistakes we just covered, a professional approach to the Hunter.io API isn’t about one-off data fetching. It’s about integrating a complete Lead Quality Lifecycle into your systems. This framework has four distinct stages, and different API endpoints map directly to each one.

The four stages are: Find, Verify, Enrich, and Maintain. Most developers stop at “Find,” which is where the problems we discussed begin. True value is unlocked by chaining all four stages together.

• Find: This is the discovery phase. You use endpoints like Domain Search or the Email Finder to get potential email addresses associated with a name and a company. This is your raw, unrefined material.
• Verify: This is the most critical and often-skipped step. You take the most promising email from the ‘Find’ stage and run it through the Email Verifier endpoint. This single action is what prevents the 32% bounce rate scenario and protects your domain reputation.
• Enrich: Once you have a verified email, you can then push that high-confidence data point into your CRM or database. You’re not just adding an email; you’re adding a verified asset. This is where you might also pull metadata from the original search, like the person’s name or job title if available.
• Maintain: Data gets stale. You can build periodic jobs that re-verify critical contacts (e.g., every 90 days) to clean out old data. This is a more advanced step but essential for long-term database health.

Implementing this full lifecycle takes an engineering team an average of 40-80 hours, or about 2-4 development sprints. However, the ROI is significant. Teams that adopt this model typically see a 25-40% reduction in email bounce rates and a 10-15% lift in positive reply rates within the first three months because they’re contacting real people at the right inbox.

With this lifecycle framework in mind, we can move from theory to practice. Here’s the step-by-step implementation guide to get your first verified lead flowing through this exact process.

Step-by-Step Implementation Guide: From Zero to First Verified Lead

Let’s apply the ‘Lead Quality Lifecycle’ framework we just established to build a foundational integration. This process will take you from generating an API key to programmatically finding and verifying your first lead. A competent developer can complete these core steps in a single workday (around 8 hours).

Step 1: Secure Your API Key

Your first move, which should take no more than 15 minutes, is to get your API key from your Hunter.io dashboard. Once you have it, the cardinal rule is: do not hardcode it in your application. Store it as an environment variable (e.g., `HUNTER_API_KEY`).

1. Log in to your Hunter.io account.
2. Navigate to the ‘API’ section in the top menu.
3. Copy your secret API key.
4. In your project, set it as an environment variable. For example, in a `.env` file: `HUNTER_API_KEY=”your_key_here”`.

This simple practice prevents your key from being accidentally committed to a public Git repository, a mistake that happens more often than you’d think and can lead to your monthly quota being exhausted by strangers in minutes.

Step 2: Make Your First Authenticated Call

Before doing anything complex, you need to confirm you can authenticate successfully. The ‘Account Information’ endpoint is perfect for this. It’s the “hello world” of the Hunter API and confirms your key works while also giving you crucial usage data. You can complete this check in about 30 minutes.

Here’s a simple example using Python’s `requests` library:

import os
import requests

API_KEY = os.getenv('HUNTER_API_KEY')

response = requests.get(
    f"https://api.hunter.io/v2/account?api_key={API_KEY}"
)

if response.status_code == 200:
    print("Successfully connected!")
    print(response.json())
else:
    print(f"Failed. Status code: {response.status_code}")

A successful run means you’re ready to access the more powerful endpoints. This step is complete when you see a JSON response with your plan details and current API call usage.

Step 3: Implement the ‘Find’ Logic (Domain Search)

Now, let’s find some emails. The Domain Search endpoint is your workhorse for discovering contacts at a company. Your goal here is to write a function that takes a domain name and returns a list of potential email addresses. Expect this to take 2-3 hours to build and test properly.

1. Create a function, for instance `find_emails_for_domain(domain)`.
2. Inside, construct the URL for the Domain Search endpoint: `https://api.hunter.io/v2/domain-search?domain={domain}&api_key={API_KEY}`.
3. Make the GET request and parse the JSON response.
4. The key you care about is `data[’emails’]`. This is a list of email objects.
5. Return the list of email values. Add error handling for non-200 status codes.

Your function is working when you can pass it `google.com` and get back a list of publicly available Google email addresses. You’ve now completed the ‘Find’ stage of our lifecycle.

Step 4: Implement the ‘Verify’ Gate (Email Verifier)

This is the step that separates amateur implementations from professional ones. Take the emails you found and check their deliverability. This logic will likely take another 2-3 hours to get right, as it involves making decisions based on the verification status.

1. Create a new function, `verify_email_deliverability(email)`.
2. Construct the URL for the Email Verifier endpoint: `https://api.hunter.io/v2/email-verifier?email={email}&api_key={API_KEY}`.
3. Make the request and parse the JSON response.
4. The critical value is `data[‘status’]`. You are looking for the value `”deliverable”`.
5. Your function should return `True` if the status is `”deliverable”` and `False` otherwise.

To tie it all together, you’ll call `find_emails_for_domain()` first. Then, you’ll loop through the results and call `verify_email_deliverability()` on each one until you find the first ‘deliverable’ address. This verified email is the golden asset you can now safely add to your CRM.

Choosing Your Integration Approach: Real-Time vs. Bulk Processing

Now that you have the basic implementation logic, the next decision is how to apply it at scale. Your choice between real-time and bulk processing will fundamentally change your application’s architecture, cost, and user experience. This isn’t a stylistic choice; it’s a strategic one based on your specific business need.

Use this simple decision heuristic to guide your choice:

• If your goal is to validate or enrich a lead the moment it enters your system (e.g., from a website signup form or a manual CRM entry), then you must use a real-time approach with the single ‘Email Verifier’ and ‘Domain Search’ endpoints.
• If your goal is to clean, audit, or enrich an existing list of hundreds or thousands of contacts (e.g., a CSV file or an entire CRM database), then you must use the ‘Bulk’ endpoints to save time, cost, and API calls.

The trade-offs are clear. Real-time processing gives you instant feedback, which is essential for user-facing applications. The sacrifice is a higher cost per lead (one or more API calls per contact) and increased complexity in handling API latency and errors gracefully within a user’s session.

Bulk processing, on the other hand, is vastly more efficient, reducing your cost per lead by a significant margin. The trade-off is latency; you submit a job and might wait anywhere from a few minutes to a few hours for the results. This makes it unsuitable for immediate feedback but perfect for backend administrative tasks.

A typical real-time verification might cost 1 API credit and take 1-3 seconds. A bulk verification of 1,000 emails might cost 500 credits but process in 15 minutes. Choosing the wrong approach, like using a real-time method to check a 10,000-contact list, would not only be 2x more expensive but would also take hours of sequential processing and almost certainly trigger rate limits.

Building on this decision framework, let’s dive into the specifics of the most common and powerful use case: enriching a CRM in real time.

Implementation Deep Dive: Real-Time Lead Enrichment in a CRM

A real-time CRM enrichment flow is one of the highest-value integrations you can build. It ensures that every new lead that enters your system is immediately checked and enhanced with a verified email address, dramatically increasing the productivity of your sales team. A well-executed integration of this type can provide a 10x return on the development investment within 12 months.

How to Do This

The architecture involves three components: your CRM, a middleware service you control, and the Hunter API. The CRM cannot call Hunter directly; your service acts as the intermediary. Many CRM platforms like HubSpot offer powerful webhook capabilities, making this a common integration pattern. For a more detailed look at how different CRMs expose their data, exploring documentation for products like Zoho can be helpful; for instance, understanding the [key endpoints in the Zoho CRM API](https://aeroleads.com/blog/zoho-crm-api-documentation-key-endpoints/) provides a useful parallel.

1. Set up a CRM Webhook: In your CRM (e.g., Salesforce, HubSpot), configure a webhook to trigger whenever a new contact is created. This webhook should send a payload containing the new contact’s ID, name, and company domain to an endpoint you control.
2. Create Your Middleware Endpoint: This can be a simple serverless function (e.g., AWS Lambda, Google Cloud Function) that receives the POST request from the CRM webhook.
3. Call Hunter’s Domain Search: From your middleware, use the domain from the webhook payload to call the Hunter.io ‘Domain Search’ endpoint.
4. Verify the Best Result: Iterate through the returned emails and call the ‘Email Verifier’ on the most likely candidate (often the one with the highest confidence score or most common pattern). Stop when you find one with a `status` of `deliverable`.
5. Update the CRM Record: Once a verified email is found, make an API call back to your CRM to update the contact record with the newly found email address.

Real Numbers

A project of this scope typically costs between $2,000 and $5,000 in developer time, representing 40-100 hours of work. The ongoing cost is your Hunter.io plan ($49-$399/month). The ROI is tangible: teams often report a 15-20% increase in sales-qualified leads within 6 months because reps are no longer wasting time on leads with bad contact data.

Common Mistakes

The most common failure mode, occurring in roughly 40% of initial implementations, is not gracefully handling the ‘no emails found’ case. If Hunter returns no results for a domain, your code must exit cleanly without erroring. It should log this outcome and potentially tag the CRM record as ‘Needs Manual Review’ instead of leaving it in a broken state.

Success Checklist

• [ ] The CRM webhook reliably fires within 5 seconds of contact creation.
• [ ] Your API key is stored securely as an environment variable in your middleware, not in code.
• [ ] Your logic correctly handles cases where the Domain Search returns an empty list.
• [ ] The entire process, from webhook to CRM update, completes in under 10 seconds.

While real-time enrichment is powerful for new leads, many organizations have years of existing, unverified data. This requires a completely different approach: bulk processing.

Mastering Bulk Operations for List Cleaning and Auditing

If you have an existing database with thousands of contacts, a real-time, one-by-one approach is wildly inefficient and expensive. Hunter’s bulk processing endpoints are designed specifically for this scenario, allowing you to clean and enrich massive datasets with just a few API calls. This is the go-to method for any large-scale data hygiene project.

How to Do This

The process involves submitting a file, waiting for Hunter to process it, and then downloading the results. This is an asynchronous workflow, so your code must be built to handle the delay.

1. Prepare Your Data: Export the list you want to clean as a CSV file. For the Bulk Email Finder, you’ll need columns for `domain`, `first_name`, and `last_name`. For Bulk Email Verifier, you just need a column of `email` addresses.
2. Write a Submission Script: Create a script (Python with `requests` is excellent for this) that makes a POST request to the appropriate bulk endpoint (e.g., `/v2/email-finder-bulk`). The body of the request will contain your list of data.
3. Implement a Polling Mechanism: The initial API response will NOT contain your results. It will contain a job ID. You must write a loop that calls the corresponding retrieval endpoint (e.g., `/v2/email-finder-bulk/{id}`) every 30-60 seconds to check the status of the job.
4. Download and Merge Results: Once the polling response indicates the job is complete, it will contain a download URL for your results file. Your script should then download this file and merge the new data back into your original dataset, matching records on email or name.

Real Numbers

Cleaning a list of 20,000 contacts using the Bulk Email Verifier typically takes 20-40 minutes of processing time on Hunter’s side. This task would consume about 10,000 API credits, which costs around $200 on the ‘Growth’ plan. The result is often a reduction in your database’s bounce rate from over 10% down to less than 2%, drastically improving your email deliverability and sender score.

Common Mistakes

A staggering 80% of developers attempting their first bulk integration fail to implement a polling mechanism. They submit the file, get a 200 OK response with a job ID, and mistakenly assume the process is finished, never retrieving their results.

Another common error is submitting a file that is too large. While the API is robust, it’s better to break a massive list (e.g., 1 million contacts) into smaller chunks of 50,000-100,000 to improve processing speed and make error handling more manageable.

Success Checklist

• [ ] Your script can correctly parse and format a source CSV file.
• [ ] Your code successfully submits the data and stores the returned job ID.
• [ ] A polling loop is in place, checking the job status at a reasonable interval (e.g., every 60 seconds).
• [ ] The script can download the results file and correctly merge it with the original data.

Whether you’re working in real-time or in bulk, you will eventually encounter a universal constraint in the world of APIs: rate limits. Understanding how to manage them is non-negotiable for building a stable application.

Managing API Rate Limits and Usage Costs

Ignoring API rate limits is like driving a car without a fuel gauge. Sooner or later, you’re going to get stranded. The Hunter.io API, like all professional services, enforces limits to ensure stability for all users. Proactively managing these limits is the difference between a reliable integration and one that constantly breaks.

How to Do This

A robust rate limit strategy is built on three pillars: monitoring, caching, and intelligent retries. This approach prevents problems before they happen.

1. Read the Response Headers: This is the most critical and most overlooked step. Every response from the Hunter API includes `X-RateLimit` headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`). Your code should read these headers after every single call and log them. This gives you a real-time view of your remaining quota.
2. Implement a Domain Cache: Before you call the Domain Search or Email Verifier for a given domain, check a local cache (like Redis or even a simple in-memory dictionary for smaller scripts). If you’ve looked up `company.com` in the last 24 hours, use the cached result instead of wasting an API call. This single technique can reduce API consumption by 50-70% in applications with repetitive lookups.
3. Use Exponential Backoff: When you do get a `429 Too Many Requests` status code, don’t just immediately retry. You’ll just get another 429. Implement an exponential backoff algorithm: wait 1 second, retry; if it fails again, wait 2 seconds, then 4, then 8, and so on. This respects the API’s request for you to slow down. For more on this, our guide to [managing API throttling and backoff strategies](https://aeroleads.com/blog/manage-api-throttling-backoff-strategies-dynamics-365/) offers deeper insights.

Real Numbers

Implementing a simple Redis cache for your application might cost as little as $5-$15 per month. For a team on the $99/month ‘Growth’ plan, this small investment can easily save them from needing to upgrade to the $199/month plan, representing a net savings of over $1,000 per year.

Common Mistakes

The most common mistake is building a retry loop that doesn’t have a maximum limit. A simple `while` loop that retries on a 429 error can run indefinitely, creating a resource-intensive loop that can crash your own server. Always include a maximum retry count (e.g., 5 attempts) before your code gives up and logs a critical error.

Success Checklist

• [ ] Your HTTP client is configured to read and log the `X-RateLimit` headers from every response.
• [ ] A caching layer is active for all domain-based lookups, with a TTL (Time To Live) of at least 12-24 hours.
• [ ] Your code includes an exponential backoff function that is triggered specifically by the 429 status code.
• [ ] Your application has a monitoring dashboard that visualizes your `X-RateLimit-Remaining` value over time.

Properly managing rate limits keeps your integration stable and cost-effective. But even with perfect code, things can still go wrong. Let’s build a troubleshooting playbook for the most common errors.

Troubleshooting Common Hunter.io API Errors

Even the best-laid plans can go awry. Knowing how to quickly diagnose and fix common API errors will save you hours of frustration. Here are the most frequent issues and their solutions.

Problem: `401 Unauthorized`
This error means your API key is invalid or missing. In 95% of cases, this is not a complex issue. It’s usually a simple copy-paste error, an extra space, or the key being wrapped in quotes when it shouldn’t be. First, regenerate your key in the Hunter dashboard and update your environment variable to be absolutely sure you have the right one.

Problem: `422 Unprocessable Entity`
This means the data you sent was syntactically correct (valid JSON), but semantically wrong. The most common cause is sending a malformed or invalid domain name (e.g., `company` instead of `company.com`). This error occurs in about 10% of calls during initial development. The solution is to implement input validation on your end *before* you ever call the API, ensuring domains are properly formatted.

Problem: `429 Too Many Requests`
As discussed, this means you’ve hit your rate limit. This isn’t just an error; it’s a critical signal that your application’s design is flawed. The immediate fix is to wait until your limit resets (check the `X-RateLimit-Reset` header for the timestamp). The long-term fix is to implement caching and exponential backoff. For more context on handling such errors, our [troubleshooting guide for API limits and error codes](https://aeroleads.com/blog/freshsales-api-rate-limits-error-codes-troubleshooting/) provides a broader framework.

Problem: Low confidence scores on returned emails.
This isn’t an error, but a misunderstanding of the data. An email with a confidence score below 75 should be treated with suspicion. A score below 50 means you have a very high chance of a bounce. Your business logic should filter these out. A good rule of thumb: only automatically use emails with a score of 80 or higher. Anything less should be flagged for manual review.

Knowing how to fix these problems is crucial, but knowing when to avoid building the integration entirely is even better. It’s time to discuss when the Hunter API isn’t the right tool for the job.

When the Hunter.io API Is the Wrong Choice

No tool is a universal solution. The Hunter.io API is specialized for B2B professional data, and using it outside of its intended purpose will lead to frustration and wasted resources. You should actively choose not to use the Hunter API under these specific conditions.

If you need consumer email addresses, this is the wrong tool.
Hunter’s database is built from public web data and focuses exclusively on professional emails (`name@company.com`). It will not find, and is not designed to find, personal emails like `@gmail.com`, `@yahoo.com`, or `@outlook.com`. If your target audience is consumers, you need a B2C data provider.

If your budget is truly zero, this is the wrong tool.
The free plan provides 25 searches and 50 verifications per month. This is only enough to build and test a proof-of-concept. For any production application with even minimal traffic, you will need a paid plan, which starts at $49/month. If you have less than that to spend, your resources are better invested in manual prospecting on platforms like LinkedIn.

If your project requires 100% guaranteed accuracy, this is the wrong tool.
Email discovery is a game of probabilities, not certainties. Hunter is one of the best, but no service is perfect. You should expect a successful find-and-verify rate of 60-80% for established companies. If your use case has zero tolerance for error (e.g., a time-sensitive legal notification), you must use a guaranteed delivery method, not an email discovery API.

If you’ve determined the Hunter API *is* the right fit for your project after considering these disqualifiers, it’s helpful to see how it stacks up against the alternative methods for acquiring lead data. Let’s compare the main approaches.

Comparison Table: Hunter.io API vs. Alternatives

Choosing how to source your lead data is a major decision with long-term consequences for your budget, data quality, and team efficiency. The Hunter.io API is just one of several options. This table provides an opinionated comparison to help you decide.

Approach	Cost	Time to Value	Complexity	Typical ROI (12 Mo.)	Best for	Avoid if
Hunter.io API Integration	$49-$399/mo + dev time	1-3 months	Medium	300%+	Automating B2B lead enrichment and verification at scale.	You need B2C data or have zero budget.
Manual Prospecting	Low (time is the cost)	Immediate but slow	Low	150%	Highly targeted, low-volume, high-value outreach.	You need to build a scalable, repeatable process.
Buying Static Lists	$0.50-$2.00 per lead	Immediate	Very Low	-20% (damages reputation)	Quickly filling a pipeline with low-quality leads for cold calling.	You care about email deliverability and brand reputation.
Building a Custom Scraper	$10k-$25k+ dev cost	6-12 months	Very High	-50% (in Year 1)	Massive scale, niche data requirements where no API exists.	You are not a data engineering company with a dedicated team.

As the table shows, the Hunter.io API occupies a powerful middle ground. It provides the scale that manual prospecting lacks, with far superior quality and safety compared to buying lists. While building a custom scraper offers ultimate control, its massive upfront cost and long development timeline make it impractical for over 99% of companies.

For most businesses looking to build a scalable B2B outreach engine, integrating a proven API like Hunter’s provides the best balance of cost, speed, and return on investment. This table should clarify where the API fits strategically. To wrap up, let’s answer the most common and specific questions developers have during an implementation.

Frequently Asked Questions (FAQ)

How much does a typical CRM integration project cost?

For a standard, real-time lead enrichment integration with a CRM like HubSpot or Salesforce, you should budget for 40 to 100 hours of development time. At typical freelance or agency rates, this translates to a project cost between $3,000 and $8,000. This includes building the middleware, handling errors, setting up caching, and thorough testing.

How long does it take to see a return on investment?

You will see immediate improvements in data quality the day you deploy. A measurable financial ROI, calculated from increased sales productivity and higher reply rates, typically becomes apparent within 3 to 6 months. The first indicator is usually a drop in your email bounce rate from 5-10% to under 2%.

What’s a realistic accuracy rate to expect from the Domain Search endpoint?

This depends heavily on the company size. For Fortune 500 companies with predictable email patterns, you can expect to find a valid email for a specific person 80-90% of the time. For small-to-medium businesses (SMBs), that rate drops to around 50-70%, as their email structures can be less consistent.

Can I use the API to find personal email addresses?

No. The Hunter.io API is designed exclusively for B2B professional email addresses (`@company.com`). It does not store or search for personal emails from providers like Gmail or Yahoo. Attempting to use it for B2C purposes will yield zero results and is a misuse of the service.

What is the most common mistake that gets an API key suspended?

The number one cause of suspension is aggressive, un-throttled retries after receiving a `429 Too Many Requests` error. This behavior mimics a denial-of-service attack. In over 80% of suspension cases, the user has implemented a simple loop that retries instantly, which floods the API and triggers automated security blocks.

How do I handle rate limits on the free plan?

The free plan’s limits (25 searches/month) are very restrictive and intended for development only. To make the most of it, you must implement aggressive caching from day one. A simple rule: your development code should never request the same domain more than once in a 24-hour period. Store every result locally to avoid wasting your limited quota.

Does the Email Verifier check if the person still works at the company?

No, and this is a critical distinction. The Email Verifier performs technical checks (SMTP server validation, etc.) to confirm if an email address can receive mail. It does not verify employment status. An email can be ‘deliverable’ even if the person left the company months ago if the company uses a catch-all address. Employment verification requires a different tool, like checking a user’s LinkedIn profile.