Hunter Getting Started: API Key & First Request (2026)

Getting started overview

Integrating with the Hunter API requires obtaining an API key from a registered account, which then authenticates requests to its various endpoints. Hunter provides endpoints for services such as Email Finder, Email Verifier, and Domain Search, designed for tasks like lead generation and email list management. The API primarily uses a RESTful architecture, allowing for straightforward HTTP requests.

This guide outlines the essential steps to get started: account creation, API key retrieval, and making a foundational API call using cURL. Understanding the structure of API requests, including parameters and response formats, is key to successful integration. Hunter's documentation provides specific examples for its core products, demonstrating how to query for email addresses associated with a domain or verify the deliverability of an email address.

Before making API calls, it's beneficial to review the Hunter API documentation to understand rate limits, error codes, and specific endpoint requirements. Adhering to these guidelines ensures efficient and compliant use of the service. For those new to APIs, resources like the MDN Web Docs on REST can provide foundational knowledge on API concepts.

Create an account and get keys

To begin using the Hunter API, you must first create a Hunter account and generate an API key. This key serves as your authentication credential for all API requests.

Account Creation

1. Navigate to the Hunter signup page.
2. Provide the required information, typically an email address and password.
3. Confirm your email address if prompted, which is a standard security measure for new accounts.

API Key Generation

Once your account is active, follow these steps to retrieve your API key:

1. Log in to your Hunter account.
2. Access your account dashboard.
3. Locate the 'API' section, which is usually found under 'Settings' or directly in the main navigation.
4. Your API key will be displayed there. It is a unique string of characters.
5. Copy this API key securely. It should be treated like a password, as it grants access to your Hunter account's API usage and associated data.

Hunter offers a free tier that includes 50 searches and 100 verifications per month, allowing initial testing without a paid subscription. For higher usage, paid plans start at $49/month.

Your first request

After obtaining your API key, you can make your first request to test the Hunter API. A common starting point is the Email Finder or Domain Search API. This example demonstrates a Domain Search request using cURL to find email addresses associated with a specific domain.

Example: Domain Search API

The Domain Search endpoint allows you to retrieve all email addresses found for a given domain, along with their sources. This is useful for lead generation or understanding the public presence of a company's email infrastructure.

Request Structure

The basic structure for a Domain Search request includes the base URL, the domain parameter, and your api_key.

curl "https://api.hunter.io/v2/domain-search?domain=example.com&api_key=YOUR_API_KEY"

Replace example.com with the domain you wish to query and YOUR_API_KEY with your actual Hunter API key.

Making the Call (cURL)

Open your terminal or command prompt and execute the cURL command:

curl "https://api.hunter.io/v2/domain-search?domain=apispine.com&api_key=sk_YOUR_API_KEY_HERE"

Upon successful execution, the API will return a JSON object containing information about the domain, including email addresses found, their types (generic, personal), and sources. An example successful response might look like this:

{
  "data": {
    "domain": "apispine.com",
    "disposable": false,
    "webmail": false,
    "pattern": "{first}.{last}@apispine.com",
    "emails": [
      {
        "value": "[email protected]",
        "type": "personal",
        "confidence": 95,
        "sources": [
          {
            "uri": "https://apispine.com/contact",
            "extracted_on": "2024-01-01",
            "link": "https://apispine.com/contact"
          }
        ],
        "first_name": "John",
        "last_name": "Doe",
        "position": "Developer"
      }
    ],
    "organization": "Apispine",
    "country": "US",
    "state": null,
    "city": null,
    "employees": null
  },
  "meta": {
    "results": 1,
    "limit": 10,
    "offset": 0
  }
}

Example: Email Verifier API

To verify the deliverability of an email address, you can use the Email Verifier endpoint.

Request Structure

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

Replace [email protected] with the email address you want to verify and YOUR_API_KEY with your actual Hunter API key.

Making the Call (cURL)

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

A successful response for an email verification will include a result field indicating the status (e.g., deliverable, undeliverable, risky).

{
  "data": {
    "email": "[email protected]",
    "result": "deliverable",
    "score": 95,
    "regexp": true,
    "gibberish": false,
    "disposable": false,
    "webmail": false,
    "mx_records": true,
    "smtp_server": true,
    "smtp_check": true,
    "accept_all": false,
    "sources": [
      {
        "uri": "https://apispine.com/contact",
        "extracted_on": "2024-01-01",
        "link": "https://apispine.com/contact"
      }
    ]
  },
  "meta": {
    "timestamp": 1678886400
  }
}

Common next steps

After successfully making your first API calls with Hunter, consider these common next steps to further integrate and optimize your usage:

1. Explore Additional Endpoints: Hunter offers several other API endpoints, including Email Finder, Bulk Email Verifier, and Author Finder. Review the Hunter API documentation to identify which services align with your project requirements.
2. Implement Error Handling: Integrate robust error handling into your application. The Hunter API returns specific HTTP status codes and error messages to help diagnose issues, such as invalid API keys, rate limit exceedances, or invalid parameters. Understanding these error responses is crucial for building resilient integrations.
3. Manage Rate Limits: Be aware of Hunter's rate limits, which specify the number of requests you can make within a given time frame. Implement a strategy to manage your request frequency, such as using exponential backoff for retries, to avoid hitting these limits and ensure consistent service availability.
4. Integrate into Your Application: Beyond cURL, consider using one of Hunter's officially supported client libraries or an HTTP client in your preferred programming language (e.g., Python's requests, Node.js's axios) to integrate the API calls directly into your application's codebase. This allows for more dynamic and programmatic interaction with the API.
5. Monitor Usage: Regularly check your API usage within your Hunter account dashboard to ensure you stay within your plan's limits. This helps prevent unexpected service interruptions or additional charges.
6. Secure Your API Key: Ensure your API key is stored securely and not exposed in client-side code or public repositories. Best practices include using environment variables or a secure configuration management system.

Troubleshooting the first call

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

• Invalid API Key:
  • Symptom: An error message indicating an invalid API key, or an HTTP 401 Unauthorized status code.
  • Solution: Double-check that you have copied your API key correctly from your Hunter dashboard API section. Ensure there are no extra spaces or missing characters.
• Rate Limit Exceeded:
  • Symptom: An error message about exceeding rate limits or an HTTP 429 Too Many Requests status code.
  • Solution: This usually means you've made too many requests in a short period. Wait for a few minutes and try again. For continuous integration, implement rate limit handling mechanisms in your code. Review the Hunter API rate limit documentation.
• Incorrect Endpoint or Parameters:
  • Symptom: An HTTP 404 Not Found error for the endpoint, or an HTTP 400 Bad Request if parameters are missing or malformed.
  • Solution: Verify that the endpoint URL (e.g., /v2/domain-search) is correct and matches the Hunter API documentation. Ensure all required parameters (like domain or email) are included and correctly formatted.
• Network Connectivity Issues:
  • Symptom: Connection timeouts or inability to reach the API server.
  • Solution: Check your internet connection. If you are behind a firewall or proxy, ensure it allows outgoing connections to api.hunter.io.
• Insufficient Monthly Quota:
  • Symptom: An error indicating that your monthly quota has been reached.
  • Solution: Check your usage statistics in your Hunter dashboard. If you've exhausted your free tier or paid plan quota, you may need to upgrade your plan or wait for the next billing cycle.

For persistent issues, consult the official Hunter API documentation or contact Hunter support directly.