Hunter.io Getting Started: API Keys & First Request (2026)

Getting started overview

Integrating with the Hunter.io API involves a sequence of steps designed to enable programmatic access to its email verification and finding services. The process generally includes account creation, API key retrieval, and executing an initial API call. Hunter.io offers a free tier that provides a limited number of monthly verifications and searches, allowing developers to test the API without an immediate financial commitment.

The Hunter.io API is designed as a RESTful interface, which means it utilizes standard HTTP methods (GET, POST) and predictable, resource-oriented URLs. Responses are delivered in JSON format, a common data interchange format for web APIs, making it compatible with most programming languages and environments. Authentication is managed through API keys, which are unique identifiers assigned to each user account to secure access and track usage.

Before making your first request, it's beneficial to review the Hunter.io API documentation. This resource provides detailed information on available endpoints, request parameters, and response structures for services such as Email Verifier, Email Finder, and Domain Search. The documentation also includes code examples in several popular programming languages, including Node.js, Python, Ruby, PHP, and Go, which can expedite the integration process.

The following table summarizes the initial steps to integrate with the Hunter.io API:

Create an account and get keys

To begin using the Hunter.io API, you must first create a user account. This account serves as your portal for managing subscriptions, viewing usage statistics, and accessing your API key. The registration process typically involves providing an email address and creating a password.

Upon successful account creation, Hunter.io automatically generates a unique API key for your account. This key is a string of alphanumeric characters that acts as a credential for authenticating your API requests. It is essential to treat your API key as sensitive information, similar to a password, to prevent unauthorized access to your account and API usage.

You can locate your API key by navigating to your Hunter.io account dashboard. Specifically, the API key is typically found within the 'API' section of your account settings. For example, the Hunter.io API key management page provides direct access to this credential. It is recommended to copy your API key and store it securely within your application's configuration or environment variables rather than embedding it directly into your source code. This practice helps prevent accidental exposure of your key, especially in version control systems.

Hunter.io offers different subscription tiers, including a free tier. The free tier provides 25 email verifications and 50 domain searches per month. This allows developers to test the API's functionality and integrate it into their applications before committing to a paid plan. Paid plans, such as the Starter plan, offer increased quotas for verifications and searches, starting at $49 per month for 500 verifications and 1,000 searches.

Your first request

Once you have obtained your API key, you can proceed to make your first API request. This section will guide you through constructing a basic request using the Email Verifier endpoint, a core product of Hunter.io, to check the validity of an email address. The Email Verifier API endpoint is designed to determine if an email address is deliverable and can identify various statuses, such as valid, invalid, or unknown.

The base URL for the Hunter.io API is https://api.hunter.io/v2/. All API endpoints are appended to this base URL. For the Email Verifier, the specific endpoint is /verifier. Your API key will be passed as a query parameter named api_key.

Here's an example of how to make an Email Verifier API request using curl, a common command-line tool for making HTTP requests:

curl "https://api.hunter.io/v2/[email protected]&api_key=YOUR_API_KEY"

Replace YOUR_API_KEY with the actual API key from your Hunter.io account and [email protected] with the email address you wish to verify. Upon executing this command, the API will return a JSON response containing information about the email address's validity. A successful response for a valid email might look like this:

{
  "data": {
    "result": "deliverable",
    "score": 95,
    "email": "[email protected]",
    "regexp": true,
    "gibberish": false,
    "disposable": false,
    "webmail": true,
    "mx_records": true,
    "smtp_server": true,
    "smtp_check": true,
    "accept_all": false,
    "block": false,
    "sources": []
  },
  "meta": {
    "params": {
      "email": "[email protected]"
    }
  }
}

The result field within the data object indicates the verification status, such as deliverable, undeliverable, or unknown. Other fields provide additional context, like a confidence score and flags for disposable email providers or webmail services. For a comprehensive understanding of all possible response parameters and their meanings, refer to the Hunter.io Email Verifier API documentation.

Common next steps

After successfully making your first API call, several common next steps can enhance your integration with Hunter.io and leverage its full capabilities. These steps often involve exploring additional API endpoints, implementing error handling, and optimizing your usage.

1. Explore other API endpoints: Hunter.io offers several other core products accessible via its API. These include:

   • Email Finder: This endpoint allows you to find the most probable email address for a person given their first name, last name, and domain name. This is particularly useful for lead generation and sales outreach. Consult the Hunter.io Email Finder documentation for details.
   • Domain Search: This endpoint returns all the email addresses found for a given domain name. It can provide insights into the email structure and publicly available contacts within an organization. More information is available in the Hunter.io Domain Search documentation.
   • Bulk Email Verifier/Finder: For processing large lists of emails or domains, Hunter.io provides bulk endpoints. These typically involve uploading a file or providing a list of items to be processed asynchronously. Review the Bulk Email Verifier API reference and Bulk Email Finder API reference for implementation details.

2. Implement robust error handling: API integrations should always account for potential errors. Hunter.io's API returns standard HTTP status codes (e.g., 400 Bad Request, 401 Unauthorized, 429 Too Many Requests, 500 Internal Server Error) along with JSON error responses. Your application should be designed to gracefully handle these responses, providing informative feedback to users or logging issues for debugging. The Hunter.io API error codes documentation details the various error types and their meanings.

3. Manage API quotas and rate limits: Each Hunter.io plan, including the free tier, comes with specific API call quotas. Exceeding these quotas or making too many requests within a short period can result in 429 Too Many Requests errors. Implement logic to monitor your usage and incorporate exponential backoff or other rate-limiting strategies if necessary to avoid hitting limits. You can check your remaining quota by examining the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset HTTP headers in API responses.

4. Secure your API key: Reiterate the importance of keeping your API key confidential. Avoid hardcoding it directly into your application's source code. Instead, use environment variables, a secrets management service, or a configuration file that is not committed to version control. This practice aligns with general API key security best practices.

5. Integrate with other services: Hunter.io data can be valuable when combined with other platforms. For example, verified emails can be used with email marketing platforms like SparkPost or customer relationship management (CRM) systems like Salesforce. The output from Hunter.io's Email Finder can directly feed into outreach automation tools.

Troubleshooting the first call

When making your initial API request to Hunter.io, you might encounter issues. Here are common problems and their potential solutions:

• Invalid API Key (HTTP 401 Unauthorized):

  • Problem: You receive an HTTP 401 status code or an error message indicating an invalid API key.
  • Solution: Double-check that you have copied your API key correctly from your Hunter.io API key page. Ensure there are no leading or trailing spaces and that the key is passed exactly as provided. Verify that the parameter name is api_key in your request URL.

• Missing Required Parameters (HTTP 400 Bad Request):

  • Problem: The API returns a 400 status code with a message about missing parameters.
  • Solution: Review the Hunter.io API documentation for the specific endpoint you are calling. For the Email Verifier, the email parameter is mandatory. Ensure all required parameters are present and correctly formatted in your request.

• Rate Limit Exceeded (HTTP 429 Too Many Requests):

  • Problem: You receive an HTTP 429 status code, indicating you've sent too many requests in a given period.
  • Solution: This can happen quickly on the free tier. Wait for the rate limit to reset (check the X-RateLimit-Reset header in the response, if available) or consider upgrading your Hunter.io plan if you need higher volumes. Implement a delay or exponential backoff in your code for repeated requests.

• Network Connectivity Issues:

  • Problem: Your request times out or fails to connect to the Hunter.io API server.
  • Solution: Verify your internet connection. If you are behind a firewall or proxy, ensure that outbound connections to api.hunter.io on port 443 (HTTPS) are permitted.

• Incorrect Endpoint URL:

  • Problem: You receive an HTTP 404 Not Found error.
  • Solution: Confirm that the API endpoint URL is correct, including the base URL (https://api.hunter.io/v2/) and the specific resource path (e.g., verifier, finder). Refer to the Hunter.io API reference to ensure the path is accurate.