API version

Introduction

You can enjoy our service's features with our simple JSON API. Three main calls are available:

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 Author Finder guesses the most likely email of a person from an article he wrote.
The Email Verifier checks the deliverability of a given email address, verifies if it has been found in our database, and returns their sources.

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:

The Leads
The Custom Attributes
The Leads Lists
The Campaigns

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.

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

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.
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"
    }
  ]
}

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.

domain Required*	Domain name from which you want to find the email addresses. For example, "stripe.com".
company Required*	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` or `communication`. Several departments can be selected (comma-delimited).
api_key Required	Your secret API key. You can generate 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.

* You must send at least the domain name or the company name. You can also send both.

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.io&api_key=API_KEY

domain Required*	The domain name of the company, used for emails. For example, "reddit.com".
company Required*	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.
first_name Required**	The person's first name. It doesn't need to be in lowercase.
last_name Required**	The person's last name. It doesn't need to be in lowercase.
full_name Required**	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 5.
api_key Required	Your secret API key. You can generate it in your dashboard.

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.

url Required	The URL of the article. For example, "https://hunter.io/blog/how-to-know-if-someone-read-your-email/". Any query parameter or fragment is ignored.
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 generate it in your dashboard.

400 `wrong_params`	`url` is missing in the parameters.
400 `invalid_url`	The supplied `url` is invalid.
400 `page_not_found`	The supplied `url` does point to a valid page.
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 article author has 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.

email Required	The email address you want to verify.
api_key Required	Your secret API key. You can generate it in your dashboard.

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.
429 `too_many_requests`	You've reached the limit for the number of verifications per domain in 24 hours. To prevent this, check the number of requests remaining per domain using the `X-Rate-Limit-Remaining` header.
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.

domain Required*	The domain name for which you want to know how many email addresses we have.
company Required*	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.
type	Get the count of only `personal` or `generic` email addresses.

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`, `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).
query	Only returns the leads with any attribute 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 generate it in your dashboard.

id Required	Identifier of the lead.
api_key Required	Your secret API key. You can generate it in your dashboard.

email 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: Animal, Art and Entertainment, Automotive, Beauty and Fitness, Books and Litterature, Education and Career, Finance, Food and Drink, Game, Health, Hobby and Leisure, Home and Garden, Industry, Internet and Telecom, Law and Government, News, Real Estate, Science, Shopping, 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 correct, between 0 and 100. In Hunter's products, the confidence score is the score returned by the Email Finder.
website	The domain name of the company.
country_code	The country of the lead. The country code is defined in the 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 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 Required	Your secret API key. You can generate it in your dashboard.

id Required	Identifier of the custom attribute.
api_key Required	Your secret API key. You can generate it in your dashboard.

label Required	The name, or label, of your custom attribute. Has to be unique.
api_key Required	Your secret API key. You can generate it in your dashboard.

limit	A limit on the number of lists to be returned. Limit can range between 1 and 100 lists. Default is 20.
offset	The number of lists to skip. Use this parameter to fetch all the lists.
api_key Required	Your secret API key. You can generate it in your dashboard.

id Required	Identifier of the leads list.
limit	A limit on the number of leads to be returned. Limit can range between 1 and 100 lists. Default is 20.
offset	The number of leads to skip. Use this parameter to fetch all the leads in the list.
api_key Required	Your secret API key. You can generate it in your dashboard.

name Required	The name of the leads list.
api_key Required	Your secret API key. You can generate it in your dashboard.

started	Only returns the campaigns that have been started.
archived	Only returns campaigns that have been archived.
limit	A limit on the number of campaigns to be returned. Limit can range between 1 and 100 campaigns. Default is 20.
offset	The number of campaigns to skip. Use this parameter to fetch all the campaigns.
api_key Required	Your secret API key. You can generate it in your dashboard.

id Required	Identifier of the campaign
emails Required	The recipients you want to add to the campaign. If there's only one email, it can be supplied as a string. Otherwise, it should be an array of up to 100 emails. In case an email doesn't pass our validation, an error is returned, and no recipient is added.
api_key Required	Your secret API key. You can generate it in your dashboard.