Introduction

You can enjoy our service's features with our simple JSON API:

  • Discover returns companies matching a set of criteria.

  • The Domain Search returns all the email addresses found using one given domain name, with sources.

  • The Email Finder finds the most likely email address from a domain name, a first name and a last name.

  • The Email Verifier checks the deliverability of a given email address, verifies if it has been found in our database, and returns their sources.

  • The Enrichment returns all the information we have about a person or a company.

Our API also provides you a RESTful way to manage your Hunter's resources. These are the resources you can Create, Read, Update and Delete with our API:

API endpoint

https://api.hunter.io/v2/

Structure

Our API is designed to be as simple to use as possible. We always use the same basic structure:

  • data contains the data you requested.

  • meta provides information regarding your request.

  • errors shows errors with insights regarding what made the request fail. Learn more about the errors responses.

Successful response

{
  "data": {
    ...
  },
  "meta": {
    ...
  }
}

Error response

{
  "errors": {
    ...
  }
}

Authentication

Authentication is made with a key you will have to add to every call you make to our API. This parameter is always required. We'll return an error if the key is either missing or invalid.

It can be passed in the api_key query parameter, in the X-API-KEY header, or in the Authorization header (Bearer YOUR_API_KEY).

Your API key is what identifies your account, so make sure to keep it secret! You can at anytime retrieve, generate or delete API keys on your dashboard.

A special API key can be used to test our API: test-api-key. It will validate the provided parameters, but will always return the same, dummy, response. It is available on our three main endpoints: the Domain Search, the Email Finder, and the Email Verifier.

Sign up to get your free API key.

Errors

Hunter's API uses conventional HTTP response codes to indicate the success or failure of an API request. In case of error, the API returns an array of errors containing information regarding what happened.

HTTP Status Code Summary
200 - OK The request was successful.
201 - Created The request was successful and the resource was created.
204 - No content The request was successful and no additional content was sent.
400 - Bad request Your request was not valid. It was missing a required parameter or a supplied
parameter was invalid.
401 - Unauthorized No valid API key was provided.
403 - Forbidden You have reached the rate limit.
404 - Not found The requested resource does not exist.
422 - Unprocessable entity Your request is valid but the creation of the resource
failed. Check the errors.
429 - Too many requests You have reached your usage limit. Upgrade your plan if
necessary.
451 - Unavailable for legal reasons We have been requested not to process personal identifiable information linked to this person.
Therefore, we cannot proceed with your request.
5XX - Server errors Something went wrong on Hunter's end.

Error example

{
  "errors": [\
    {\
      "id": "wrong_params",\
      "code": 400,\
      "details": "You are missing the domain parameter"\
    }\
  ]
}

Discover

Returns companies matching a set of criteria. This call is free.

Each response will return a maximum of 100 companies. Premium users can use the offset and limit parameters to paginate through results. The limit parameter allows you to request fewer than 100 companies per page if needed.

You can use our other endpoints to get more information about the returned results. For instance, you can find email addresses for the surfaced companies using the Domain Search , or you can get more information about the companies using Company Enrichment.

You can either manually specify the filters for your search using the specific filter parameters, or use natural language with the query parameter to describe the attributes of your target companies, and an AI assistant will select appropriate filters for you.

Requirements: You must provide either query (natural language) or at least one filter parameter.
query
required unless a filter is set		 Search query, in your natural language. For example, "Companies in Europe in the Tech Industry".
organization You can specify a list of domains in the domain field to select on and/or a list of
company names in the name field to select on. When you supply both, the API will
combine the results into a set of domain names.
similar_to You can either specify a domain or a name of a company to find similar
companies for. If you specify both then the domain will be used.
This filter is only available on a Premium plan.
headquarters_location Locations of the headquarters of the companies you want to find.
You can specify lists of locations in the include field to select on and/or in the exclude field to exclude.
Each location can have either a
continent or business_region or country, state
and/or city.
continent can be one of the following:
Europe, Asia, North America, Africa, Antarctica, South America or Oceania
business_region can be one of the following:
AMER, EMEA, APAC or LATAM
country must contain a valid ISO 3166-1 alpha-2 country code, for example "US" for the
United States.
state must contain a valid US state code, for example "CA" for California. You can only use
this field when the country is set to "US".
city must contain a city name, for example "San Francisco".
Please note that when a city is provided, a country must also be specified:
<br>{<br> "headquarters_location": {<br> "include": [<br> { "city": "Paris", "country": "FR" }<br> ]<br> }<br>}<br>
industry The industries you want to select companies by, you can specify a list of industries to
include and/or a list to exclude. See
industries.json
for the list of valid industries.
headcount The company sizes you want to include in the results. The possible values are
1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000 or 10001+
company_type The types of companies you want to select on. You can specify a list of types to include
and/or exclude. The possible values are
educational, educational institution, government agency, non profit, partnership, privately held, public company, self employed, self owned or sole proprietorship
year_founded
Premium only		 The years in which the companies were founded, for example "2010". You can specify either multiple years
to include and/or exclude or you can specify a range by giving a value for
from and/or to.
This filter is only available on a Premium plan.
keywords Keywords to narrow down your selection of companies. You can specify a list of keywords in the
include field to select on and/or a list in the exclude field to exclude
from the results. You can specify to match on any or all keywords in the
match field (the default value is all).
technology
Premium only		 Technologies to narrow down your selection of companies. You can specify a list of technologies in the
include field to select on and/or a list in the exclude field to exclude
from the results. You can specify to match on any or all technologies in the
match field (the default value is all). See
technologies.json
for the list of valid technologies.
This filter is only available on a Premium plan.
funding
Premium only		 You can provide a list of funding series in the series field to narrow down your selection
of companies. The possible values are
pre_seed, seed, pre_series_a, series_a, pre_series_b, series_b, pre_series_c, series_c+ or other
You can also specify a range of funding amounts in the amount field, you can specify a
from and/or to value
Finally you can also specify a range of funding dates in the date field, here you can also
specify a from and/or to value.
This filter is only available on a Premium plan.
limit
Premium only		 Specifies the number of companies to return per page. The default
and maximum values are 100. You can use this parameter to request fewer results per page
(e.g., 50 or 25). You can only change the limit if you are on a Premium plan.
offset
Premium only		 Specifies the number of companies to skip. The default
is 0. The maximum value is 10,000. You can only change the offset if you are on a Premium plan.
api_key
required		 Your secret API key. You can retrieve it in your
dashboard.

Each response will return up to 100 companies (this is the maximum per request). Use the offset parameter to paginate through more results, up to a maximum offset of 10,000 (this requires a Premium plan).

filters in the meta section returns the filters that were applied based on the input parameters. If you want to paginate the results of the AI assistant, we strongly recommend using these filters instead of natural language on consecutive calls—this will ensure your set of desired filters stays consistent.

The Discover API endpoint is rate limited to 5 requests per second and 50 requests per minute.

Errors

Here are the errors specific to the Discover API call. If you can't find an error in the list, please also check the general API errors.
400invalid_company_type One of the supplied company_type values is invalid.
400invalid_funding One of the supplied funding input is invalid.
400invalid_funding_series One of the supplied funding[series] values is invalid.
400invalid_funding_date_from The supplied funding[date][from] is invalid.
400invalid_funding_date_to The supplied funding[date][to] is invalid.
400invalid_funding_date_range The funding[date][from] must be before the funding[date][to].
400invalid_funding_amount_from The supplied funding[amount][from] is invalid.
400invalid_funding_amount_to The supplied funding[amount][to] is invalid.
400invalid_funding_amount_range The funding[amount][to] must be greater than the funding[amount][from].
400invalid_headcount One of the supplied headcount values is invalid.
400invalid_headquarters_location The supplied headquarters_location input is not valid.
400invalid_headquarters_location_include_combination The combination of values in a headquarters_location[include] value is invalid.
400invalid_headquarters_location_include_business_region The headquarters_location[include][business_region] value is invalid.
400invalid_headquarters_location_include_continent The headquarters_location[include][continent] value is invalid.
400invalid_headquarters_location_include_country The headquarters_location[include][country] value is invalid.
400invalid_headquarters_location_include_state The headquarters_location[include][state] value is given while the country is
not US or is not a valid US state code.
400invalid_headquarters_location_exclude_combination The combination of values in a headquarters_location[exclude] value is invalid.
400invalid_headquarters_location_exclude_business_region The headquarters_location[exclude][business_region] value is invalid.
400invalid_headquarters_location_exclude_continent The headquarters_location[exclude][continent] value is invalid.
400invalid_headquarters_location_exclude_country The headquarters_location[exclude][country] value is invalid.
400invalid_headquarters_location_exclude_state The headquarters_location[exclude][state] value is given while the country is
not US or is not a valid US state code
400invalid_industry One of the supplied industry values is invalid.
400invalid_keywords The supplied keywords input is not valid.
400invalid_keywords_match The value in the keywords[match] field must be either any or all.
400invalid_technology One of the supplied technology values is invalid.
400invalid_technology_match The value in the technology[match] field must be either any or all..
400invalid_year_founded_combination The combination of fields used in year_founded is invalid.
400invalid_year_founded_include One of the values supplied in year_founded[include] is invalid.
400invalid_year_founded_from The supplied year_founded[from] value is invalid.
400invalid_year_founded_to The supplied year_founded[to] value is invalid.
400pagination_error The supplied limit or offset is invalid.
This error can also be returned when changing the default values for a Free plan user.
403no_discover_access Your plan does not include access to the Discover endpoint (applies to Data Platform users).

HTTP request example

POST https://api.hunter.io/v2/discover?api_key=API_KEY

Get my free API key

Request Body

{
  "organization": {
    "domain": ["hunter.io"]
  }
}

Response: 200 OK

{
  "data": [\
    {\
      "domain": "hunter.io",\
      "organization": "Hunter",\
      "emails_count": {\
        "personal": 23,\
        "generic": 5,\
        "total": 28\
      }\
    }\
  ],
  "meta": {
    "results": 1,
    "limit": 100,
    "offset": 0,
    "params": {
      "organization": {
        "domain": [\
          "hunter.io"\
        ],
      }
    },
    "filters": {
      "organization": {
        "domain": [\
          "hunter.io",\
        ]
      }
    }
  }
}

Request Body using the AI assistant

{
  "query": "Companies in Europe that specialize in software development"
}

Request Body using various filters

{
  "headquarters_location": {
    "include": [\
      { "continent": "Europe" },\
      { "country": "US" }\
    ],
    "exclude": [\
      { "country": "BE" }\
    ]
  },
  "industry": {
    "exclude": [\
      "Accommodation Services",\
      "Staffing and Recruiting"\
    ]
  },
  "headcount": [\
    "1-10",\
    "11-50",\
    "51-200"\
  ],
  "company_type": {
    "exclude": [\
      "educational",\
      "non profit",\
      "government agency"\
    ]
  },
  "year_founded": {
    "from": 1980,
    "to": 2010
  },
  "technology": {
    "match": "any",
    "include": [\
      "php",\
      "java"\
    ]
  }
}

Domain Search

One key feature of Hunter is to search all the email addresses corresponding to one website. You give one domain name and it returns all the email addresses using this domain name found on the internet.

Requirements: You must provide at least one of domain or company. If both are provided, domain takes precedence.
domain
required unless company		 Domain name from which you want to find the email
addresses. For example, "stripe.com".
company
required unless domain		 The company name from which you want to find the email
addresses. For example, "stripe". Note that you'll get better
results by supplying the domain name as we won't have to find
it. If you send a request with both the domain and the company
name, we'll use the domain name. It doesn't need to be in
lowercase.
limit Specifies the max number of email addresses to return. The default
is 10.
offset Specifies the number of email addresses to skip. The default
is 0.
type Get only
personal or generic
email addresses.
seniority Get only email addresses for people with the selected seniority level.
The possible values are
junior, senior or executive.
Several seniority levels can be
selected (delimited by a comma).
department Get only email addresses for people working in the selected
department(s). The possible values are
executive, it, finance, management, sales, legal, support, hr, marketing, communication, education, design, health or operations.
Several departments can be selected (comma-delimited).
required_field Get only email addresses for people that have the selected field(s).
The possible values are
full_name, position and phone_number.
Several fields can be selected (comma-delimited).
verification_status Get only email addresses that have the selected verification status(es).
The possible values are
valid, accept_all and unknown.
Several statuses can be selected (comma-delimited).
location Get only email addresses for people with the selected location(s).
You can specify lists of locations in the include field to select on and/or in the exclude field to exclude.
Each location can have either a
continent or business_region or country, state
and/or city.
continent can be one of the following:
Africa, Antarctica, Asia, Europe, North America, Oceania or South America
business_region can be one of the following:
AMER, EMEA, APAC or LATAM
country must contain a valid ISO 3166-1 alpha-2 country code, for example "US" for the
United States.
state must contain a valid US state code, for example "CA" for California. You can only use
this field when the country is set to "US".
city must contain a city name, for example "San Francisco".
Please note that when a city is provided, a country must also be specified:
<br>{<br> "location": {<br> "include": [<br> { "city": "Paris", "country": "FR" }<br> ]<br> }<br>}<br>
Please note that using this filter requires to use a POST request.
job_titles Get only email addresses for people that have the selected job title(s).
Several job titles can be selected (comma-delimited).
api_key
required		 Your secret API key. You can retrieve it in your
dashboard.

Each response will return up to 100 emails. Use the "offset" parameter to get all of them. A new query is counted for calls returning at least one result.

The number of sources is limited to 20 for each email address. The extracted_on attribute of a source contains the date it was found for the first time, whereas the last_seen_on attribute contains the date it was found for the last time.

type returns the value "personal" or "generic". A "generic" email address is a role-based email address, like contact@hunter.io. On the contrary, a "personal" email address is the address of someone in the company.

confidence is our estimation of the probability the email address returned is correct. It depends on several criteria such as the number and quality of sources.

The Domain Search API endpoint is rate limited to 15 requests per second and 500 requests per minute.

Errors

Here are the errors specific to the Domain Search API call. If you can't find an error in the list, please also check the general API errors.
400
wrong_params		 domain or company is missing in the parameters.
400
invalid_type		 The supplied type is invalid.
400
invalid_seniority		 The supplied seniority is invalid.
400
invalid_department		 The supplied department is invalid.
400
pagination_error		 The supplied limit or offset is invalid.
This error can also be returned if the limit additioned to
the offset is higher than 10 for a Free plan user.

HTTP request example

GET https://api.hunter.io/v2/domain-search?domain=intercom.com&api_key=API_KEY

Get my free API key

Response: 200 OK

{
  "data": {
    "domain": "intercom.com",
    "disposable": false,
    "webmail": false,
    "accept_all": true,
    "pattern": "{first}",
    "organization": "Intercom",
    "linked_domains": [],
    "emails": [\
      {\
        "value": "ciaran@intercom.com",\
        "type": "personal",\
        "confidence": 92,\
        "sources": [\
          {\
            "domain": "github.com",\
            "uri": "http://github.com/ciaranlee",\
            "extracted_on": "2015-07-29",\
            "last_seen_on": "2017-07-01",\
            "still_on_page": true\
          },\
          {\
            "domain": "blog.intercom.com",\
            "uri": "http://blog.intercom.com/were-hiring-a-support-engineer/",\
            "extracted_on": "2015-08-29",\
            "last_seen_on": "2017-07-01",\
            "still_on_page": true\
          },\
          ...\
        ],\
        "first_name": "Ciaran",\
        "last_name": "Lee",\
        "position": "Support Engineer",\
        "position_raw": "Support Engineer",\
        "seniority": "senior",\
        "department": "it",\
        "linkedin": null,\
        "twitter": "ciaran_lee",\
        "phone_number": null,\
        "verification": {\
          "date": "2019-12-06",\
          "status": "valid"\
        }\
      },\
      ...\
    ]
  },
  "meta": {
    "results": 35,
    "limit": 10,
    "offset": 0,
    "params": {
      "domain": "intercom.com",
      "company": null,
      "type": null,
      "seniority": null,
      "department": null
    }
  }
}

Email Finder

This API endpoint finds the most likely email address from a domain name, a first name and a last name.

Requirements: You must provide at least one of domain, company, or linkedin_handle. You must also provide a name — either first_name + last_name, or full_name — unless linkedin_handle is provided.
domain
required unless company or linkedin_handle		 The domain name of the company.
company
required unless domain or linkedin_handle		 The company name from which you want to find the email
addresses. For example, "stripe". Note that providing the
domain name gives better results as it removes the
conversion from the company name.
If you send a request with both the domain and the company
name, the domain name will be used. The company name
doesn't need to be in lowercase.
linkedin_handle
required unless domain or company		 The handle of the LinkedIn profile for which you to find the email address.
first_name
required unless full_name or linkedin_handle		 The person's first name. It doesn't need to be
in lowercase.
last_name
required unless full_name or linkedin_handle		 The person's last name. It doesn't need to be
in lowercase.
full_name
required unless first_name and last_name, or linkedin_handle		 The person's full name. Note that you'll get better results
by supplying the person's first and last name if you can.
It doesn't need to be in lowercase.
max_duration The maximum duration of the request in seconds. Setting a
longer duration allows us to refine the results and provide
more accurate data. It must range between 3 and 20. The default
is 10.
api_key
required		 Your secret API key. You can retrieve it in your
dashboard.

A verification is automatically performed on each email found. If no email can be found, no credit is charged. The verification information is displayed in verification. The possible statuses are valid, accept_all, and unknown.

For accept-all emails, the score estimates the probability that the email address is valid.

If the email address can be found publicly on the web, the URLs are returned in sources. The extracted_on attribute contains the date it was found for the first time, whereas the last_seen_on attribute contains the date it was found for the last time. The number of sources that can be returned is limited to 20.

The Email Finder API endpoint is rate limited to 15 requests per second and 500 requests per minute.

Errors

Here are the errors specific to the Email Finder API call. If you can't find an error in the list, please also check the general API errors.
400
wrong_params		 A required parameter is missing.
400
invalid_first_name		 The supplied first_name is invalid.
400
invalid_last_name		 The supplied last_name is invalid.
400
invalid_full_name		 The supplied full_name is invalid.
400
invalid_domain		 The domain name is invalid, has no MX record or its owner has asked us
to stop the processing of the associated data.
400
invalid_max_duration		 The supplied max_duration is invalid.
451
claimed_email		 The person owning the email address asked us directly or indirectly to stop
the processing of their personal data. For this reason, you shouldn't
process it yourself in any way.

HTTP request example

GET https://api.hunter.io/v2/email-finder?domain=reddit.com&first_name=Alexis&last_name=Ohanian&api_key=API_KEY

Get my free API key

Response: 200 OK

{
  "data": {
    "first_name": "Alexis",
    "last_name": "Ohanian",
    "email": "alexis@reddit.com",
    "score": 97,
    "domain": "reddit.com",
    "accept_all": false,
    "position": "Cofounder",
    "twitter": null,
    "linkedin_url": null,
    "phone_number": null,
    "company": "Reddit",
    "sources": [\
      {\
        "domain": "redditblog.com",\
        "uri": "http://redditblog.com/2008/10/22/widgets-get-an-upgrade-and-a-firefox-extension-that-will-rock-your-world",\
        "extracted_on": "2018-10-19",\
        "last_seen_on": "2021-05-18",\
        "still_on_page": true\
      },\
      ...\
    ],
    "verification": {
      "date": "2021-06-14",
      "status": "valid"
    }
  },
  "meta": {
    "params": {
      "first_name": "Alexis",
      "last_name": "Ohanian",
      "full_name": null,
      "domain": "reddit.com",
      "company": null,
      "max_duration": null
    }
  }
}

Email Verifier

This API endpoint allows you to verify the deliverability of an email address.

The request will run for 20 seconds. If it was not able to provide a response in time, we will return a 202 status code. You will then be able to poll the same endpoint to get the verification's result. Of course, all the requests in this case are counted only once.
email
required		 The email address you want to verify.
api_key
required		 Your secret API key. You can retrieve it in your
dashboard.

status returns the status of the email address. It takes 1 out of 6 possible values:

  • "valid": the email address is valid.

  • "invalid": the email address is not valid.

  • "accept_all": the email address is valid but any email address is accepted by the server.

  • "webmail": the email address comes from an email service provider such as Gmail or Outlook.

  • "disposable": the email address comes from a disposable email service provider.

  • "unknown": we failed to verify the email address.

result returns the main status of the verification. It takes 1 out of 3 possible values:

  • "deliverable": the email verification is successful and the email address is valid.

  • "undeliverable": the email address is not valid.

  • "risky": the verification can't be validated.

It is deprecated; use status instead to get the detailed status of the email address.

score is the deliverability score we give to the email address. For webmail and disposable emails, we provide an arbitrary score of 50.

regexp is true if the email address passes our regular expression.

gibberish is true if we find this is an automatically generated email address (for example "e65rc109q@company.com").

disposable is true if we find this is an email address from a disposable email service.

webmail is true if we find this is an email from a webmail (for example Gmail).

mx_records is true if we find MX records exist on the domain of the given email address.

smtp_server is true if we connect to the SMTP server successfully.

smtp_check is true if the email address doesn't bounce.

accept_all is true if the SMTP server accepts all the email addresses. It means you can have have false positives on SMTP checks.

block is true if the SMTP server prevented us to perform the SMTP check.

sources If we have found the given email address somewhere on the web, we display the sources here. The number of sources is limited to 20. The extracted_on attribute contains the date it was found for the first time, whereas the last_seen_on attribute contains the date it was found for the last time.

The Email Verifier API endpoint is rate limited to 10 requests per second and 300 requests per minute.

Errors

Here are the errors specific to the Email Verifier API call. If you can't find an error in the list, please also check the general API errors.
202 The verification is still in progress. Feel free to make the API call
again as often as necessary. It will only count as a single request until
we return the response.
222 The verification failed because of an unexpected response from the remote SMTP
server. This failure is outside of our control. We recommend to retry later.
400
wrong_params		 The email parameter is missing.
400
invalid_email		 The supplied email is invalid.
451
claimed_email		 The person owning the email address asked us directly or indirectly to
stop the processing of their personal data. For this reason, you shouldn't
process it yourself in any way.

HTTP request example

GET https://api.hunter.io/v2/email-verifier?email=patrick@stripe.com&api_key=API_KEY

Get my free API key

Response: 200 OK

{
  "data": {
    "status": "valid",
    "score": 100,
    "email": "patrick@stripe.com",
    "regexp": true,
    "gibberish": false,
    "disposable": false,
    "webmail": false,
    "mx_records": true,
    "smtp_server": true,
    "smtp_check": true,
    "accept_all": false,
    "block": false,
    "sources": [\
      {\
        "domain": "beta.paganresearch.io",\
        "uri": "http://beta.paganresearch.io/details/stripe",\
        "extracted_on": "2020-06-17",\
        "last_seen_on": "2020-06-17",\
        "still_on_page": true\
      },\
      {\
        "domain": "icloudnewz.blogspot.com",\
        "uri": "http://icloudnewz.blogspot.com/2017/11/follow-patrick-collison-mike-birbiglia.html",\
        "extracted_on": "2020-03-25",\
        "last_seen_on": "2020-06-29",\
        "still_on_page": true\
      }\
    ]
  },
  "meta": {
    "params": {
      "email": "patrick@stripe.com"
    }
  }
}

Enrichment

Our Enrichment endpoints allow you to retrieve all the information we have about a person, a company, or both.

Here is the list of the available endpoints:

Email Enrichment

Returns all the information associated with an email address or LinkedIn handle, such as a person's name, location and social handles.

Requirements: You must provide at least one of email or linkedin_handle. When both are provided, linkedin_handle takes precedence.
email
required unless linkedin_handle		 The email address name for which you to find associated information.
linkedin_handle
required unless email		 The handle of the LinkedIn profile for which you to find associated information.
api_key
required		 Your secret API key. You can retrieve it in your
dashboard.
clearbit_format As more customers switch to Clearbit, we've updated the Enrichment API to support the same Clearbit schema. Any value you provide will now be formatted to match Clearbit's schema for consistency.

If we can find the person we'll return a 200 status containing the person's attributes.

If we can't find any information associated with the email address, we'll return a 404 status.

The Email Enrichment API endpoint is rate limited to 15 requests per second and 500 requests per minute.

HTTP request example

GET https://api.hunter.io/v2/people/find?email=matt@hunter.io&api_key=API_KEY

Get my free API key

Response: 200 OK

{
  "data": {
    "id": "b3ae14fb-6725-56d1-ac68-a76f8ce04dec",
    "name": {
      "fullName": "Matthew Tharp",
      "givenName": "Matthew",
      "familyName": "Tharp"
    },
    "email": "matt@hunter.io",
    "location": "Framingham, Massachusetts, United States",
    "timeZone": "America/New_York",
    "utcOffset": -5,
    "geo": {
      "city": "Framingham",
      "state": "Massachusetts",
      "stateCode": "MA",
      "country": "United States",
      "countryCode": "US",
      "lat": 42.27926,
      "lng": -71.41617
    },
    "bio": null,
    "site": null,
    "avatar": null,
    "employment": {
      "domain": "hunter.io",
      "name": "Hunter",
      "title": "Chief Executive Officer",
      "role": "executive",
      "subRole": null,
      "seniority": "executive"
    },
    "facebook": {
      "handle": null
    },
    "github": {
      "handle": null,
      "id": null,
      "avatar": null,
      "company": null,
      "blog": null,
      "followers": null,
      "following": null
    },
    "twitter": {
      "handle": "matttharp",
      "id": null,
      "bio": null,
      "followers": null,
      "following": null,
      "statuses": null,
      "favorites": null,
      "location": null,
      "site": null,
      "avatar": null
    },
    "linkedin": {
      "handle": "matttharp"
    },
    "googleplus": {
      "handle": null
    },
    "gravatar": {
      "handle": null,
      "urls": [],
      "avatar": null,
      "avatars": []
    },
    "fuzzy": false,
    "emailProvider": "google.com",
    "indexedAt": "2025-08-30",
    "phone": null,
    "activeAt": "2025-09-03",
    "inactiveAt": null
  },
  "meta": {
    "email": "matt@hunter.io"
  }
}

Company Enrichment

Returns all the information associated with a domain name, such as the industry, the description, or headquarters' location.
domain
required		 The domain name for which you to find associated information.
api_key
required		 Your secret API key. You can retrieve it in your
dashboard.
clearbit_format As more customers switch to Clearbit, we've updated the Enrichment API to support the same Clearbit schema. Any value you provide will now be formatted to match Clearbit's schema for consistency.

If we can find the company we'll return a 200 status containing the company's attributes.

If we can't find any information associated with the domain name, we'll return a 404 status.

The Company Enrichment API endpoint is rate limited to 15 requests per second and 500 requests per minute.

HTTP request example

GET https://api.hunter.io/v2/companies/find?domain=hunter.io&api_key=API_KEY

Get my free API key

Response: 200 OK

{
  "data": {
    "id": "95ca56a8-a019-5c41-881e-293d9ca4741a",
    "name": "Hunter",
    "legalName": "Hunter",
    "domain": "hunter.io",
    "domainAliases": [],
    "site": {
      "phoneNumbers": [\
        "+1 415 712 0049"\
      ],
      "emailAddresses": [\
        "support@hunter.io",\
        "security@hunter.io",\
        "contact@hunter.io",\
        "engineering@hunter.io",\
        "affiliates@hunter.io",\
        "press@hunter.io"\
      ]
    },
    "category": {
      "sector": "Information Technology",
      "industryGroup": "Software & Services",
      "industry": "Internet Software & Services",
      "subIndustry": "Internet",
      "gicsCode": "45103010",
      "sicCode": "36",
      "sic4Codes": [\
        "73"\
      ],
      "naicsCode": "51",
      "naics6Codes": [\
        "519130"\
      ],
      "naics6Codes2022": [\
        "519290"\
      ]
    },
    "tags": [\
      "email marketing",\
      "lead generation",\
      "data enrichment",\
      "sales intelligence",\
      "business tools"\
    ],
    "description": "Hunter is an email marketing company that specializes in lead generation and data enrichment.",
    "foundedYear": 2015,
    "location": "Wilmington, Delaware, United States",
    "timeZone": "America/New_York",
    "utcOffset": -5,
    "geo": {
      "streetNumber": null,
      "streetName": null,
      "subPremise": null,
      "streetAddress": null,
      "city": "Wilmington",
      "postalCode": null,
      "state": "Delaware",
      "stateCode": "DE",
      "country": "United States",
      "countryCode": "US",
      "lat": 39.74595,
      "lng": -75.54659
    },
    "logo": "https://logos.hunter.io/hunter.io",
    "facebook": {
      "handle": null,
      "likes": null
    },
    "linkedin": {
      "handle": "company/hunterio"
    },
    "twitter": {
      "handle": null,
      "id": null,
      "bio": null,
      "followers": null,
      "following": null,
      "location": null,
      "site": null,
      "avatar": null
    },
    "crunchbase": {
      "handle": null
    },
    "instagram": {
      "handle": null
    },
    "emailProvider": "google.com",
    "type": "private",
    "company_type": "privately held",
    "ticker": null,
    "identifiers": {
      "usEIN": null
    },
    "phone": "+1 415 712 0049",
    "metrics": {
      "alexaUsRank": null,
      "alexaGlobalRank": null,
      "trafficRank": "very_high",
      "employees": "11-50",
      "marketCap": null,
      "raised": null,
      "annualRevenue": null,
      "estimatedAnnualRevenue": null,
      "fiscalYearEnd": null
    },
    "indexedAt": "2024-09-09",
    "tech": [\
      "cloudflare",\
      "cloudflare-browser-insights",\
      "hsts",\
      "http-3",\
      "ruby",\
      "stimulus"\
    ],
    "techCategories": [\
      "analytics",\
      "dns",\
      "marketing_automation",\
      "programming_framework",\
      "security",\
      "web_servers"\
    ],
    "fundingRounds": [],
    "parent": {
      "domain": null
    },
    "ultimateParent": {
      "domain": null
    }
  },
  "meta": {
    "domain": "hunter.io"
  }
}

Combined Enrichment

Returns all the information associated with an email address and its domain name.
email
required		 The email address name for which you to find associated information.
api_key
required		 Your secret API key. You can retrieve it in your
dashboard.
clearbit_format As more customers switch to Clearbit, we've updated the Enrichment API to support the same Clearbit schema. Any value you provide will now be formatted to match Clearbit's schema for consistency.

If we can find the person we'll return a 200 status containing the person and their company's attributes.

If we can't find any information associated with the email, we'll return a 404 status.

The Combined Enrichment API endpoint is rate limited to 15 requests per second and 500 requests per minute.

HTTP request example

GET https://api.hunter.io/v2/combined/find?email=matt@hunter.io&api_key=API_KEY

Get my free API key

Response: 200 OK

{
  "data": {
    "person": {
      "id": "b3ae14fb-6725-56d1-ac68-a76f8ce04dec",
      "name": {
        "fullName": "Matthew Tharp",
        "givenName": "Matthew",
        "familyName": "Tharp"
      },
      "email": "matt@hunter.io",
      "location": "Framingham, Massachusetts, United States",
      "timeZone": "America/New_York",
      "utcOffset": -5,
      "geo": {
        "city": "Framingham",
        "state": "Massachusetts",
        "stateCode": "MA",
        "country": "United States",
        "countryCode": "US",
        "lat": 42.27926,
        "lng": -71.41617
      },
      "bio": null,
      "site": null,
      "avatar": null,
      "employment": {
        "domain": "hunter.io",
        "name": "Hunter",
        "title": "Chief Executive Officer",
        "role": "executive",
        "subRole": null,
        "seniority": "executive"
      },
      "facebook": {
        "handle": null
      },
      "github": {
        "handle": null,
        "id": null,
        "avatar": null,
        "company": null,
        "blog": null,
        "followers": null,
        "following": null
      },
      "twitter": {
        "handle": "matttharp",
        "id": null,
        "bio": null,
        "followers": null,
        "following": null,
        "statuses": null,
        "favorites": null,
        "location": null,
        "site": null,
        "avatar": null
      },
      "linkedin": {
        "handle": "matttharp"
      },
      "googleplus": {
        "handle": null
      },
      "gravatar": {
        "handle": null,
        "urls": [],
        "avatar": null,
        "avatars": []
      },
      "fuzzy": false,
      "emailProvider": "google.com",
      "indexedAt": "2025-08-30",
      "phone": null,
      "activeAt": "2025-09-03",
      "inactiveAt": null
    },
    "company": {
      "id": "95ca56a8-a019-5c41-881e-293d9ca4741a",
      "name": "Hunter",
      "legalName": "Hunter",
      "domain": "hunter.io",
      "domainAliases": [],
      "site": {
        "phoneNumbers": [\
          "+1 415 712 0049"\
        ],
        "emailAddresses": [\
          "support@hunter.io",\
          "security@hunter.io",\
          "contact@hunter.io",\
          "engineering@hunter.io",\
          "affiliates@hunter.io",\
          "press@hunter.io"\
        ]
      },
      "category": {
        "sector": "Information Technology",
        "industryGroup": "Software & Services",
        "industry": "Internet Software & Services",
        "subIndustry": "Internet",
        "gicsCode": "45103010",
        "sicCode": "36",
        "sic4Codes": [\
          "73"\
        ],
        "naicsCode": "51",
        "naics6Codes": [\
          "519130"\
        ],
        "naics6Codes2022": [\
          "519290"\
        ]
      },
      "tags": [\
        "email marketing",\
        "lead generation",\
        "data enrichment",\
        "sales intelligence",\
        "business tools"\
      ],
      "description": "Hunter is an email marketing company that specializes in lead generation and data enrichment.",
      "foundedYear": 2015,
      "location": "Wilmington, Delaware, United States",
      "timeZone": "America/New_York",
      "utcOffset": -5,
      "geo": {
        "streetNumber": null,
        "streetName": null,
        "subPremise": null,
        "streetAddress": null,
        "city": "Wilmington",
        "postalCode": null,
        "state": "Delaware",
        "stateCode": "DE",
        "country": "United States",
        "countryCode": "US",
        "lat": 39.74595,
        "lng": -75.54659
      },
      "logo": "https://logos.hunter.io/hunter.io",
      "facebook": {
        "handle": null,
        "likes": null
      },
      "linkedin": {
        "handle": "company/hunterio"
      },
      "twitter": {
        "handle": null,
        "id": null,
        "bio": null,
        "followers": null,
        "following": null,
        "location": null,
        "site": null,
        "avatar": null
      },
      "crunchbase": {
        "handle": null
      },
      "instagram": {
        "handle": null
      },
      "emailProvider": "google.com",
      "type": "private",
      "company_type": "privately held",
      "ticker": null,
      "identifiers": {
        "usEIN": null
      },
      "phone": "+1 415 712 0049",
      "metrics": {
        "alexaUsRank": null,
        "alexaGlobalRank": null,
        "trafficRank": "very_high",
        "employees": "11-50",
        "marketCap": null,
        "raised": null,
        "annualRevenue": null,
        "estimatedAnnualRevenue": null,
        "fiscalYearEnd": null
      },
      "indexedAt": "2024-09-09",
      "tech": [\
        "cloudflare",\
        "cloudflare-browser-insights",\
        "hsts",\
        "http-3",\
        "ruby",\
        "stimulus"\
      ],
      "techCategories": [\
        "analytics",\
        "dns",\
        "marketing_automation",\
        "programming_framework",\
        "security",\
        "web_servers"\
      ],
      "fundingRounds": [],
      "parent": {
        "domain": null
      },
      "ultimateParent": {
        "domain": null
      }
    }
  },
  "meta": {
    "email": "maat@hunter.io"
  }
}

Email Count

This API endpoint allows you to know how many email addresses we have for one domain or for one company.

Requirements: You must provide at least one of domain or company. If both are provided, domain takes precedence.
domain
required unless company		 The domain name for which you want to know how many email
addresses we have.
company
required unless domain		 The company name for which you want to know how many email
addresses we have. For example, "stripe". Note that you'll
get better results by supplying the domain name as we won't
have to find it. If you send a request with both the domain
and the company name, we'll use the domain name. It doesn't
need to be in lowercase. It must be composed of at least 3
characters.
api_key
required		 Your secret API key. You can retrieve it in your
dashboard.
type Get the count of only
personal or generic
email addresses.

The Email Count API endpoint is rate limited to 15 requests per second.

Errors

Here are the errors specific to the Email Count API call. If you can't find an error in the list, please also check the general API errors.
400
wrong_params		 domain or company is missing in the parameters.
400
invalid_type		 The supplied type is invalid.

HTTP request example

GET https://api.hunter.io/v2/email-count?domain=stripe.com&api_key=API_KEY

Get my free API key

Response: 200 OK

{
  "data": {
    "total": 81,
    "personal_emails": 65,
    "generic_emails": 16,
    "department": {
      "executive": 10,
      "it": 0,
      "finance": 8,
      "management": 0,
      "sales": 0,
      "legal": 0,
      "support": 6,
      "hr": 0,
      "marketing": 0,
      "communication": 2,
      "education": 0,
      "design": 0,
      "health": 0,
      "operations": 0
    },
    "seniority": {
      "junior": 13,
      "senior": 5,
      "executive": 2
    }
  },
  "meta": {
    "params": {
      "domain": "stripe.com",
      "company": null,
      "type": null
    }
  }
}

Account Information

This API endpoint enables you to get information regarding your Hunter account at any time. This call is free.
api_key
required		 Your secret API key. You can retrieve it in your
dashboard.

calls is the sum of search and verification requests made during the current billing period. It is deprecated; use requests instead to get the detailed usage per request type.

HTTP request example

GET https://api.hunter.io/v2/account?api_key=API_KEY

Get my free API key

Response: 200 OK

{
  "data": {
    "first_name": "Antoine",
    "last_name": "Finkelstein",
    "email": "antoine@hunter.io",
    "plan_name": "Growth",
    "plan_level": 2,
    "reset_date": 2026-05-07,
    "team_id": 1,
    "requests": {
      "credits": {
        "used": 550.0,
        "available": 10000.0
      },
      "searches": {
        "used": 500,
        "available": 10000
      },
      "verifications": {
        "used": 100,
        "available": 20000
      }
    },
    "calls": {
      "_deprecation_notice": "Sums the searches and the verifications, giving an unprecise look of the requests available",
      "used": 18526,
      "available": 20000
    }
  }
}

Leads

Saving and managing leads in Hunter can be done entirely through the RESTful API.

Here is the list of the available methods:

All these calls are free.

List all your leads

Returns all the leads already saved in your account. The leads are returned in sorted order, with the most recent leads appearing first.

The leads can be filtered by attributes. Three kind of values can be given:

  • *: select all the leads where the attribute has any value.

  • ~: select all the leads where the attribute is empty.

  • Any other string: select all the leads where the attribute contains the given value.

These filtering options apply for the following attributes: email, first_name, last_name, position, company, industry, website, country_code, company_size, source, twitter, linkedin_url and phone_number.
leads_list_id Only returns the leads belonging to this list.
email Filters the leads by email.
first_name Filters the leads by first name.
last_name Filters the leads by last name.
position Filters the leads by position.
company Filters the leads by company.
industry Filters the leads by industry.
website Filters the leads by website.
country_code Filters the leads by country.
The country code is defined in the ISO 3166-1
alpha-2 standard.
company_size Filters the leads by company size.
source Filters the leads by source.
twitter Filters the leads by Twitter handle.
linkedin_url Filters the leads by LinkedIn URL.
phone_number Filters the leads by phone number.
sync_status Only returns the leads matching this synchronization status.
It can be one of the following values:
pending, error or success.
sending_status[] Only returns the leads matching these sending status(es).
It can be some of the following values:
clicked, opened, sent, pending, error, bounced, unsubscribed, replied or ~
(unset).
verification_status[] Only returns the leads matching these verification status(es).
It can be some of the following values:
accept_all, disposable, invalid, unknown, valid, webmail or pending.
last_activity_at Only returns the leads matching this last activity.
It can be one of the following values:
* (any value) or ~ (unset).
last_contacted_at Only returns the leads matching this last contact date.
It can be one of the following values:
* (any value) or ~ (unset).
custom_attributes[] Filters the leads by custom attributes. The key of this field must match the slug of the custom
attribute you wish to filter on, the value can be * (any value), ~ (unset)
or any other string.
query Only returns the leads with first_name, last_name or email matching the query.
limit A limit on the number of leads to be returned. Limit can range
between 1 and 1,000. Default is 20.
offset The number of leads to skip. Use this parameter to fetch all
the leads. Offset can range between 0 and 100,000.
api_key
required		 Your secret API key. You can retrieve it in your
dashboard.

HTTP request example

GET https://api.hunter.io/v2/leads?api_key=API_KEY

Get my free API key

Response: 200 OK

{
  "data": {
    "leads": [\
      {\
        "id": 1,\
        "email": "hoon@stripe.com",\
        "first_name": "Jeremy",\
        "last_name": "Hoon",\
        "position": null,\
        "company": "Stripe",\
        "company_industry": null,\
        "company_size": null,\
        "confidence_score": null,\
        "website": "stripe.com",\
        "country_code": null,\
        "source": null,\
        "linkedin_url": null,\
        "phone_number": null,\
        "twitter": null,\
        "sync_status": null,\
        "notes": null,\
        "sending_status": null,\
        "last_activity_at": null,\
        "last_contacted_at": null,\
        "verification": {\
          "date": "2021-01-01 12:00:00 UTC",\
          "status": "deliverable"\
        },\
        "leads_list": {\
          "id": 1,\
          "name": "My leads list",\
          "leads_count": 2\
        },\
        "created_at": "2021-01-01 12:00:00 UTC"\
      },\
      {\
        "id": 2,\
        "email": "alexis@reddit.com",\
        "first_name": "Alexis",\
        "last_name": "Ohanian",\
        "position": "Cofounder",\
        "company": "Reddit",\
        "company_industry": null,\
        "company_size": null,\
        "confidence_score": 97,\
        "website": "reddit.com",\
        "country_code": "US",\
        "source": null,\
        "linkedin_url": null,\
        "phone_number": null,\
        "twitter": null,\
        "sync_status": null,\
        "notes": null,\
        "sending_status": null,\
        "last_activity_at": null,\
        "last_contacted_at": null,\
        "verification": {\
          "date": "2021-01-01 12:00:00 UTC",\
          "status": "deliverable"\
        },\
        "leads_list": {\
          "id": 1,\
          "name": "My leads list",\
          "leads_count": 2\
        },\
        "created_at": "2021-01-01 12:00:00 UTC"\
      }\
    }\
  },\
  "meta": {\
    "count": 2,\
    "total": 2,\
    "params": {\
      "limit": 20,\
      "offset": 0\
    }\
  }\
}\
```\
\
## [Get a lead](/content/api-documentation\#get-lead/index.html)\
\
Retrieves all the fields of a lead.\
\
|     |     |\
| --- | --- |\
| **id**<br>required | Identifier of the lead. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
GET https://api.hunter.io/v2/leads/1?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Response: 200 OK\
\
```\
{\
  "data": {\
    "id": 1,\
    "email": "hoon@stripe.com",\
    "first_name": "Jeremy",\
    "last_name": "Hoon",\
    "position": null,\
    "company": "Stripe",\
    "company_industry": null,\
    "company_size": null,\
    "confidence_score": null,\
    "website": "stripe.com",\
    "country_code": null,\
    "source": null,\
    "linkedin_url": null,\
    "phone_number": null,\
    "twitter": null,\
    "sync_status": null,\
    "notes": null,\
    "sending_status": null,\
    "last_activity_at": null,\
    "last_contacted_at": null,\
    "verification": {\
      "date": "2021-01-01 12:00:00 UTC",\
      "status": "deliverable"\
    },\
    "leads_list": {\
      "id": 1,\
      "name": "My leads list",\
      "leads_count": 2\
    },\
    "created_at": "2021-01-01 12:00:00 UTC"\
  }\
}\
```\
\
## [Create a lead](/content/api-documentation\#create-lead/index.html)\
\
Creates a new lead. The parameters must be passed as a JSON hash.\
\
|     |     |\
| --- | --- |\
| **email**<br>required | The email address of the lead. |\
| **first\_name** | The first name of the leads. |\
| **last\_name** | The last name of the lead. |\
| **position** | The job title of the lead. |\
| **company** | The name of the company the lead is working in. |\
| **company\_industry** | The sector of the company. It can be any value, but we recommend using one of the following:<br>Animal, Art & Entertainment, Automotive, Beauty & Fitness, Books & Literature, Education & Career, Finance, Food & Drink, Game, Health, Hobby & Leisure, Home & Garden, Industry, Internet & Telecom, Law & Government, Manufacturing, News, Real Estate, Science, Retail, Sport, Technology or Travel. |\
| **company\_size** | The size of the company the lead is working in. |\
| **confidence\_score** | Estimation of the probability the email address returned is<br>correct, between 0 and 100. In Hunter's products, the<br>confidence score is the score returned by the<br>[Email Finder](/content/api-documentation#email-finder/index.html). |\
| **website** | The domain name of the company. |\
| **country\_code** | The country of the lead. The country code is defined in the<br>ISO 3166-1 alpha-2 standard. |\
| **linkedin\_url** | The address of the public profile on LinkedIn. |\
| **phone\_number** | The phone number of the lead. |\
| **twitter** | The Twitter handle of the lead. |\
| **notes** | Some personal notes about the lead. |\
| **source** | The source where the lead has been found. |\
| **leads\_list\_id** | The identifier of the list the lead belongs to. If it's not<br>specified, the lead is saved in the last list created. |\
| **leads\_list\_ids** | The identifiers of the lists the lead belongs to. If it's not<br>specified, the lead is saved in the last list created. |\
| **custom\_attributes\[slug\]** | The value of the custom attribute identified by its slug. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
POST https://api.hunter.io/v2/leads?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Request Body\
\
```\
{\
  "email": "alexis@reddit.com",\
  "first_name": "Alexis",\
  "last_name": "Ohanian",\
  "position": "Cofounder",\
  "company": "Reddit",\
  "company_industry": "Internet & Telecom",\
  "company_size": "201-500 employees",\
  "confidence_score": 97,\
  "website": "reddit.com",\
  "custom_attributes": {\
    "customer_id": "cus-1234abcd"\
  }\
}\
```\
\
Response: 201 Created\
\
```\
{\
  "data": {\
    "id": 3,\
    "email": "alexis@reddit.com",\
    "first_name": "Alexis",\
    "last_name": "Ohanian",\
    "position": "Cofounder",\
    "company": "Reddit",\
    "company_industry": "Internet & Telecom",\
    "company_size": "201-500 employees",\
    "confidence_score": 97,\
    "website": "reddit.com",\
    "country_code": null,\
    "source": null,\
    "linkedin_url": null,\
    "phone_number": null,\
    "twitter": null,\
    "sync_status": null,\
    "notes": null,\
    "sending_status": null,\
    "last_activity_at": null,\
    "last_contacted_at": null,\
    "verification": {\
      "date": null,\
      "status": null\
    },\
    "customer_id": "cus1234-abcd",\
    "leads_list": {\
      "id": 1,\
      "name": "My leads list",\
      "leads_count": 3\
    },\
    "created_at": "2021-01-01 12:00:00 UTC"\
  }\
}\
```\
\
## [Create or update a lead](/content/api-documentation\#upsert-lead/index.html)\
\
Creates a new lead if it doesn't exist yet based on email address, or updates it if it does. The updated values must be passed as a\
JSON hash.\
\
The fields you can update are the same params you can give\
when you [create a lead](/content/api-documentation#create-lead/index.html).\
\
HTTP request example\
\
```\
PUT https://api.hunter.io/v2/leads?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Request Body\
\
```\
{\
  "email": "alexis@reddit.com",\
  "first_name": "Alexis",\
  "last_name": "Ohanian"\
}\
```\
\
Response: 201 Created when resource is created, 200 OK when resource is updated\
\
```\
{\
  "data": {\
    "id": 3,\
    "email": "alexis@reddit.com",\
    "first_name": "Alexis",\
    "last_name": "Ohanian",\
    "position": "Cofounder",\
    "company": "Reddit",\
    "company_industry": "Internet & Telecom",\
    "company_size": "201-500 employees",\
    "confidence_score": 97,\
    "website": "reddit.com",\
    "country_code": null,\
    "source": null,\
    "linkedin_url": null,\
    "phone_number": null,\
    "twitter": null,\
    "sync_status": null,\
    "notes": null,\
    "sending_status": null,\
    "last_activity_at": null,\
    "last_contacted_at": null,\
    "verification": {\
      "date": null,\
      "status": null\
    },\
    "customer_id": "cus1234-abcd",\
    "leads_list": {\
      "id": 1,\
      "name": "My leads list",\
      "leads_count": 3\
    },\
    "created_at": "2021-01-01 12:00:00 UTC"\
  }\
}\
```\
\
## [Update a lead](/content/api-documentation\#update-lead/index.html)\
\
Updates an existing lead. The updated values must be passed as a\
JSON hash.\
\
The fields you can update are the same params you can give\
when you [create a lead](/content/api-documentation#create-lead/index.html).\
\
HTTP request example\
\
```\
PUT https://api.hunter.io/v2/leads/1?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Request Body\
\
```\
{\
  "company": "Facebook"\
}\
```\
\
Response: 204 No Content\
\
## [Delete a lead](/content/api-documentation\#delete-lead/index.html)\
\
Deletes an existing lead.\
\
|     |     |\
| --- | --- |\
| **id**<br>required | Identifier of the lead. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
DELETE https://api.hunter.io/v2/leads/1?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Response: 204 No Content\
\
# [Custom Attributes](/content/api-documentation\#custom-attributes/index.html)\
\
Saving and managing your custom attributes in Hunter\
can be done entirely through the RESTful API.\
\
Here is the list of the available methods:\
\
- [List all your custom attributes](/content/api-documentation#list-custom-attributes/index.html)\
- [Retrieve one of your custom attribute](/content/api-documentation#get-custom-attribute/index.html)\
- [Create a new custom attribute](/content/api-documentation#create-custom-attribute/index.html)\
- [Update an existing custom attribute](/content/api-documentation#update-custom-attribute/index.html)\
- [Delete an existing custom attribute](/content/api-documentation#delete-custom-attribute/index.html)\
\
All these calls are free.\
\
## [List all your custom attributes](/content/api-documentation\#list-custom-attributes/index.html)\
\
Returns all the custom attributes already saved in your account.\
The custom attributes are returned in sorted order, with the most\
recent custom attributes appearing first.\
\
|     |     |\
| --- | --- |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
GET https://api.hunter.io/v2/leads_custom_attributes?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Response: 200 OK\
\
```\
{\
  "data": {\
    "leads_custom_attributes": [\
      {\
        "id": 2,\
        "label": "Customer ID",\
        "slug": "customer_id"\
      },\
      {\
        "id": 1,\
        "label": "Campaign ID",\
        "slug": "campaign_id"\
      }\
    ]\
  },\
  "meta": {\
    "total": 2,\
  }\
}\
```\
\
## [Get a custom attribute](/content/api-documentation\#get-custom-attribute/index.html)\
\
Retrieves all the fields of a custom attribute.\
\
|     |     |\
| --- | --- |\
| **id**<br>required | Identifier of the custom attribute. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
GET https://api.hunter.io/v2/leads_custom_attributes/1?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Response: 200 OK\
\
```\
{\
  "data": {\
    "id": 1,\
    "label": "Campaign ID",\
    "slug": "campaign_id"\
  }\
}\
```\
\
## [Create a custom attribute](/content/api-documentation\#create-custom-attribute/index.html)\
\
Creates a new custom attribute. The parameters must be passed as a JSON hash.\
\
|     |     |\
| --- | --- |\
| **label**<br>required | The name, or label, of your custom attribute. Has to be unique. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
POST https://api.hunter.io/v2/leads_custom_attributes?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Request Body\
\
```\
{\
  "label": "Campaign ID"\
}\
```\
\
Response: 201 Created\
\
```\
{\
  "data": {\
    "id": 1,\
    "label": "Campaign ID",\
    "slug": "campaign_id"\
  }\
}\
```\
\
## [Update a custom attribute](/content/api-documentation\#update-custom-attribute/index.html)\
\
Updates an existing custom attribute. The updated values must be passed as a\
JSON hash.\
\
The fields you can update are the same params you can give\
when you [create a custom attribute](/content/api-documentation#create-custom-attribute/index.html).\
\
HTTP request example\
\
```\
PUT https://api.hunter.io/v2/leads_custom_attributes/1?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Request Body\
\
```\
{\
  "label": "Outreach Campaign ID"\
}\
```\
\
Response: 204 No Content\
\
## [Delete a custom attribute](/content/api-documentation\#delete-custom-attribute/index.html)\
\
Deletes an existing custom attribute.\
\
|     |     |\
| --- | --- |\
| **id**<br>required | Identifier of the custom attribute. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
DELETE https://api.hunter.io/v2/leads_custom_attributes/1?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Response: 204 No Content\
\
# [Leads Lists](/content/api-documentation\#leads-lists/index.html)\
\
Saving and managing leads lists in Hunter can be done entirely\
through the RESTful API.\
\
Here is the list of the available methods:\
\
- [List all your leads lists](/content/api-documentation#list-leads-lists/index.html)\
- [Retrieve one of your leads lists](/content/api-documentation#get-leads-list/index.html)\
- [Create a new leads list](/content/api-documentation#create-leads-list/index.html)\
- [Update an existing leads list](/content/api-documentation#update-leads-list/index.html)\
- [Delete an existing leads list](/content/api-documentation#delete-leads-list/index.html)\
\
All these calls are free.\
\
## [List all your leads lists](/content/api-documentation\#list-leads-lists/index.html)\
\
Returns all the leads lists already saved in your account. The leads\
lists are returned in sorted order, with the most recent leads lists\
appearing first.\
\
|     |     |\
| --- | --- |\
| **limit** | A limit on the number of lists to be returned. Limit can range<br>between 1 and 100 lists. Default is 20. |\
| **offset** | The number of lists to skip. Use this parameter to fetch all<br>the lists. |\
| **api\_key**<br>required | Your secret API key. You can generate it in your dashboard. |\
\
HTTP request example\
\
```\
GET https://api.hunter.io/v2/leads_lists?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Response: 200 OK\
\
```\
{\
  "data": {\
    "leads_lists": [\
      {\
        "id": 1,\
        "name": "My first list",\
        "leads_count": 10,\
        "created_at": "2021-01-01 12:00:00 UTC"\
      },\
      {\
        "id": 2,\
        "name": "My second list",\
        "leads_count": 1,\
        "created_at": "2021-01-01 12:00:01 UTC"\
      },\
    }\
  },\
  "meta": {\
    "total": 2,\
    "params": {\
      "limit": 20,\
      "offset": 0\
    }\
  }\
}\
```\
\
## [Get a leads list](/content/api-documentation\#get-leads-list/index.html)\
\
Retrieves all the fields of a leads list.\
\
|     |     |\
| --- | --- |\
| **id**<br>required | Identifier of the leads list. |\
| **limit** | A limit on the number of leads to be returned. Limit can range<br>between 1 and 100 lists. Default is 20. |\
| **offset** | The number of leads to skip. Use this parameter to fetch all<br>the leads in the list. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
GET https://api.hunter.io/v2/leads_lists/1?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Response: 200 OK\
\
```\
{\
  "data": {\
    "id": 1,\
    "name": "My leads",\
    "leads_count": 10,\
    "created_at": "2021-01-01 12:00:00 UTC",\
    "leads": [\
      {\
        "id": 1,\
        "first_name": "Jeremy",\
        "last_name": "Hoon",\
        "position": null,\
        "company": "Stripe",\
        "company_industry": null,\
        "company_size": null,\
        "email": "hoon@stripe.com",\
        "confidence_score": null,\
        "website": "https://stripe.com",\
        "country_code": null,\
        "source": null,\
        "linkedin_url": null,\
        "phone_number": null,\
        "twitter": null,\
        "sync_status": null,\
        "notes": null,\
        "sending_status": null,\
        "last_activity_at": null,\
        "last_contacted_at": null,\
        "verification": {\
          "date": "2021-01-01 12:00:00 UTC",\
          "status": "deliverable"\
        },\
        "leads_list_id": 1,\
        "created_at": "2021-01-01 12:00:00 UTC"\
      },\
      ...\
    ]\
  },\
  "meta": {\
    "params": {\
      "limit": 20,\
      "offset": 0,\
      "leads_list_id": 1\
    }\
  }\
}\
```\
\
## [Create a leads list](/content/api-documentation\#create-leads-list/index.html)\
\
Creates a new leads list. The parameters must be passed as a JSON hash.\
\
|     |     |\
| --- | --- |\
| **name**<br>required | The name of the leads list. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
POST https://api.hunter.io/v2/leads_lists?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Request Body\
\
```\
{\
  "name": "My new leads list",\
}\
```\
\
Response: 201 Created\
\
```\
{\
  "data": {\
    "id": 3,\
    "name": "My new leads list",\
    "leads_count": 0,\
    "created_at": "2021-01-01 12:00:00 UTC"\
  }\
}\
```\
\
## [Update a leads list](/content/api-documentation\#update-leads-list/index.html)\
\
Updates an existing leads list. The updated values must be passed as a\
JSON hash.\
\
|     |     |\
| --- | --- |\
| **name**<br>required | The name of the leads list. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
PUT https://api.hunter.io/v2/leads_lists/1?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Request Body\
\
```\
{\
  "name": "New leads list name"\
}\
```\
\
Response: 204 No Content\
\
## [Delete a leads list](/content/api-documentation\#delete-leads-list/index.html)\
\
Deletes an existing leads list.\
\
|     |     |\
| --- | --- |\
| **id**<br>required | Identifier of the leads list. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
DELETE https://api.hunter.io/v2/leads_lists/1?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Response: 204 No Content\
\
# [Email Sequences](/content/api-documentation\#campaigns/index.html)\
\
You can interact with your email sequences programmatically. It enables\
you to automate advanced use-cases and make your outreach even more\
efficient.\
\
Not all endpoints are available for public usage at the moment. If\
you have a specific idea in mind that requires we open this access,\
please reach out!\
\
Here is the list of the available methods:\
\
- [List all your sequences](/content/api-documentation#list-campaigns/index.html)\
- [List the recipients of a sequence](/content/api-documentation#list-recipients/index.html)\
- [Add a recipient to a sequence](/content/api-documentation#create-recipient/index.html)\
- [Cancel scheduled emails to a recipient](/content/api-documentation#cancel-scheduled-emails/index.html)\
- [Start a sequence](/content/api-documentation#start-campaign/index.html)\
\
All these calls are free.\
\
## [List all your sequences](/content/api-documentation\#list-campaigns/index.html)\
\
Returns all the sequences in your account. The sequences\
are returned in reverse-chronological order by creation date.\
\
|     |     |\
| --- | --- |\
| **started** | Only returns the sequences that have been started. |\
| **archived** | Only returns sequences that have been archived. |\
| **limit** | A limit on the number of sequences to be returned. Limit can range<br>between 1 and 100 sequences. Default is 20. |\
| **offset** | The number of sequences to skip. Use this parameter to fetch all<br>the sequences. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
GET https://api.hunter.io/v2/campaigns?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Response: 200 OK\
\
```\
{\
  "data": {\
    "campaigns": [\
      {\
        "id": 2,\
        "name": "January tourism CTO outreach",\
        "recipients_count": 39,\
        "editable": true,\
        "started": true,\
        "archived": false,\
        "paused": false\
      },\
      {\
        "id": 1,\
        "name": "Long-term customers upsell",\
        "recipients_count": 85,\
        "editable": true,\
        "started": true,\
        "archived": false,\
        "paused": true\
      }\
    ]\
  },\
  "meta": {\
    "limit": 20,\
    "offset": 0\
  }\
}\
```\
\
## [List the recipients of a sequence](/content/api-documentation\#list-recipients/index.html)\
\
Returns all the recipients of a sequence. The recipients\
are returned in chronological order by addition date.\
\
|     |     |\
| --- | --- |\
| **limit** | A limit on the number of sequences to be returned. Limit can range<br>between 1 and 100 sequences. Default is 20. |\
| **offset** | The number of sequences to skip. Use this parameter to fetch all<br>the sequences. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
GET https://api.hunter.io/v2/campaigns/1/recipients?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Response: 200 OK\
\
```\
{\
  "data": {\
    "recipients": [\
      {\
        "email": "hoon@stripe.com",\
        "first_name": "Jeremy",\
        "last_name": "Hoon",\
        "position": null,\
        "company": "Stripe",\
        "website": "stripe.com",\
        "sending_status": "pending",\
        "lead_id": 1\
      },\
      {\
        "email": "alexis@reddit.com",\
        "first_name": "Alexis",\
        "last_name": "Ohanian",\
        "position": "Cofounder",\
        "company": "Reddit",\
        "website": "reddit.com",\
        "sending_status": "pending",\
        "lead_id": 2\
      }\
    ]\
  },\
  "meta": {\
    "limit": 20,\
    "offset": 0\
  }\
}\
```\
\
## [Add a recipient](/content/api-documentation\#create-recipient/index.html)\
\
Add a recipient to a sequence. The parameters must be passed as a JSON hash.\
\
As the recipient is added, we try to associate it with one of your\
leads with the same email, or create a new lead in your current list\
if there's no match. This enables you to send personalized emails by\
using attributes.\
\
The response contains the\
`skipped_recipients`\
array with emails that were not added to the sequence with the corresponding reason.\
The %code reason\
can be one of:\
\
- `duplicate`\
\- email is already added to the sequence\
\
- `invalid`\
\- email has invalid format\
\
- `removed`\
\- email was already removed from the sequence\
\
- `bounced`\
\- previous email sent to this recipient bounced\
\
- `unsubscribed`\
\- recipient unsubscribed from your emails\
\
- `claimed`\
\- recipient decided not to receive any emails\
\
\
**Note that when adding a recipient to an active sequence, the**\
**email might be sent shortly after your API call, leaving you no**\
**time to cancel the sending in case of a mistake.**\
\
**Requirements:** You must provide at least one of `emails` or `lead_ids`. Both can be provided together.\
\
|     |     |\
| --- | --- |\
| **id**<br>required | Identifier of the sequence |\
| **emails**<br>required unless lead\_ids | The recipients you want to add to the sequence. If there's<br>only one email, it can be supplied as a string. Otherwise, it<br>should be an array of up to 50 emails.<br>In case an email doesn't pass our validation, an error is<br>returned, and no recipient is added. |\
| **lead\_ids**<br>required unless emails | The lead IDs you want to add to the sequence. It<br>should be an array of up to 50 lead IDs.<br>In case a lead cannot be found, an error is returned, and no recipients are added. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
POST https://api.hunter.io/v2/campaigns/42/recipients?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Request Body\
\
```\
{\
  "emails": ["marcus@hunter.io", "john@hunter.io"],\
  "lead_ids": [1, 2]\
}\
```\
\
Response: 201 Created\
\
```\
{\
  "data": {\
    "recipients_added": 1,\
    "skipped_recipients": [\
      {\
        "email": "john@hunter.io",\
        "reason": "duplicate"\
      }\
    ]\
  },\
  "meta": {\
    "params": {\
      "emails": ["marcus@hunter.io", "john@hunter.io"]\
    }\
  }\
}\
```\
\
## [Cancel scheduled emails to a recipient](/content/api-documentation\#cancel-scheduled-emails/index.html)\
\
Cancel scheduled messages to a recipient from a sequence. The parameters\
must be passed as a JSON hash.\
\
Only scheduled messages from the provided sequence to the provided recipients\
will be canceled.\
\
|     |     |\
| --- | --- |\
| **id**<br>required | Identifier of the sequence |\
| **emails**<br>required | The recipients you want to cancel the scheduled messages to. If there's<br>only one email, it can be supplied as a string. Otherwise, it<br>should be an array of up to 50 emails.<br>In case an email doesn't pass our validation, an error is<br>returned, and no messages are canceled. |\
| **api\_key**<br>required | Your secret API key. You can retrieve it in your<br>[dashboard](/content/api-keys/index.html). |\
\
HTTP request example\
\
```\
DELETE https://api.hunter.io/v2/campaigns/42/recipients?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Request Body\
\
```\
{\
  "emails": ["marcus@hunter.io"]\
}\
```\
\
Response: 201 Created\
\
```\
{\
  "data": {\
    "recipients_canceled": ["marcus@hunter.io"],\
    "messages_canceled": 1\
  },\
  "meta": {\
    "params": {\
      "emails": ["marcus@hunter.io"]\
    }\
  }\
}\
```\
\
## [Start a sequence](/content/api-documentation\#start-campaign/index.html)\
\
Start a sequence. The sequence must be in the draft state to be started.\
\
The response contains the\
`recipients_count`\
key with the number of recipients in the sequence and a\
`message`\
that indicates when the sequence will start.\
\
|     |     |\
| --- | --- |\
| **id**<br>required | Identifier of the sequence. Must in the draft state, with recipients and content set. |\
\
HTTP request example\
\
```\
POST https://api.hunter.io/v2/campaigns/42/start?api_key=API_KEY\
```\
\
[Get my free API key](/content/users/sign_up?from=api/index.html)\
\
Request Body\
\
```\
{}\
```\
\
Response: 200 OK\
\
```\
{\
  "data": {\
    "message": "42 emails scheduled for sending.",\
    "recipients_count": 21\
  }\
}\
```\
\
# [Logos](/content/api-documentation\#logos/index.html)\
\
This API endpoint allows you to get the logo of any company by providing\
its domain name. It returns the logo image directly (not JSON).\
\
|     |     |\
| --- | --- |\
| **domain**<br>required | The domain name of the company for which you want to get the logo.<br>For example, "hunter.io" or "stripe.com". |\
\
## Response\
\
The API returns the logo image directly with the appropriate content type.\
Supported formats include PNG, WEBP, and AVIF.\
\
|     |     |\
| --- | --- |\
| **200** | The logo was found and is returned as an image. |\
| **404** | The logo is not currently in our database. We will automatically<br>attempt to find the logo for future requests. |\
\
This API does not require authentication.\
\
HTTP request example\
\
```\
GET https://logos.hunter.io/hunter.io\
```\
\
[Open](https://logos.hunter.io/hunter.io)\
\
Response: 200 OK\
\
```\
Content-Type: image/png, image/webp, or image/avif\
\
[Binary image data]\
```\
\
# [API wrappers](/content/api-documentation\#api-wrappers/index.html)\
\
These wrappers can help you get started faster with Hunter's API.\
\
They have been built by the community. You can contribute to the projects or\
[contact us](/content/contact/index.html)\
to have a new wrapper listed.\
\
- [Ruby](https://github.com/davidesantangelo/emailhunter)\
- [Node.js](https://www.npmjs.com/package/hunterio)\
- [Python](https://github.com/VonStruddle/PyHunter)\
- [Laravel](https://github.com/messerli90/hunterio)\
- [Go](https://github.com/picatz/hunter)\
- [R](https://github.com/dschmeh/hunteR)\
\
You can also integrate Hunter's API in your workflow without writing a line\
of code with Hunter's\
[Zapier](https://zapier.com/zapbook/hunter/)\
integration.\
\
# [Model Context Protocol (MCP)](/content/api-documentation\#mcp/index.html)\
\
Our remote MCP (Model Context Protocol) server provides integration between our API and any LLM that supports the MCP protocol (e.g., OpenAI's Responses API or Claude for Desktop),\
allowing you to interact with the Hunter B2B data using natural language.\
\
The Hunter MCP server is available at `https://mcp.hunter.io`:\
\
- Use `https://mcp.hunter.io/sse` for Server-Sent Events transport\
- Use `https://mcp.hunter.io/mcp` for Streamable HTTP transport (recommended — Use this for OpenAI's Responses API)\
\
Note that using our MCP server requires a valid Hunter API key, which can be provided in the request headers using one of:\
\
- The `Authorization` header with the format `Bearer HUNTER_API_KEY`\
- The `X-API-KEY` header with the value of your Hunter API key\
\
Example of using our MCP server with OpenAI's Responses API:\
\
```\
  curl https://api.openai.com/v1/responses\
    -H "Content-Type: application/json"\
    -H "Authorization: Bearer YOUR_OPENAI_API_KEY"\
    -d '{\
    "model": "gpt-4.1",\
    "tools": [\
      {\
        "type": "mcp",\
        "server_label": "hunter-remote-mcp",\
        "server_url": "https://mcp.hunter.io/mcp",\
        "require_approval": "never",\
        "headers": { "X-API-KEY": "YOUR_HUNTER_API_KEY" }\
      }\
    ],\
    "input": "YOUR_INPUT"\
  }'\
```\
\
For Claude Desktop, you can use the following MCP server configuration:\
\
```\
{\
  "mcpServers": {\
    "hunter-remote-mcp": {\
      "command": "npx",\
      "args": [\
        "mcp-remote",\
        "https://mcp.hunter.io/sse",\
        "--header",\
        "X-API-KEY:YOUR_HUNTER_API_KEY"\
      ]\
    }\
  }\
}\
```\
\
We use cookies\
\
We use cookies to analyze how Hunter's website is used and personalize your experience. [Learn more](/content/cookie-policy/index.html)\
\
Manage\
\
Opt-out\
\
Accept all\
\
StripeM-Inner