image/svg+xml

Back to Hunter

Get a free API key

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 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:

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 or in the X-API-KEY header.

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.

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.
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, communication, education, design, health or operations. Several departments can be selected (comma-delimited).
required_field Get only email addresses that have the selected field(s). The possible values are full_name, position, phone_number. Several fields 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 and 500 requests per minute.

* 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.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",
    "description": "Faster resolutions, higher CSAT, and lighter support volumes with the only platform to combine the power of automation and human customer support.",
    "industry": "Software Development",
    "twitter": null,
    "facebook": null,
    "linkedin": null,
    "instagram": null,
    "youtube": null,
    "technologies": ["amazon-web-services", "facebook", "intercom", "marketo", "node-js", "react", "recaptcha", "sentry"],
    "country": null,
    "state": null,
    "city": null,
    "postal_code": null,
    "street": null,
    "headcount": "501-1000",
    "company_type": "Educational Institution",
    "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",
        "seniority": "senior",
        "department": "it",
        "linkedin": null,
        "twitter": "ciaran_lee",
        "phone_number": null,
        "verification": {
          "date": "2019-12-06",
          "status": "valid"
        }
      },
      ...
    ],
    "linked_domains": []
  },
  "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.

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 10.
api_key
Required
 Your secret API key. You can generate it in your dashboard.

If a verification could be run recently on the email address, the related information is displayed in verification. The possible statuses are valid, accept_all, and unknown.

The score is an estimation of the probability the email address returned is correct.

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.

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

** You must send at least the first name and the last name or the full name.

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.

This endpoint imposes a daily rate limit based on the domain name. You can check the number of requests remaining on the domain using the X-Rate-Limit-Remaining header.

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 generate 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.
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.

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",
    "result": "deliverable",
    "_deprecation_notice": "Using result is deprecated, use status instead",
    "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"
    }
  }
}

Email Count

This API endpoint allows you to know how many email addresses we have for one domain or for one company. It's free and doesn't require authentication.

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.

This call is free and doesn't require your API key. You can use it to quickly know if we can supply email addresses on a given domain or company.

The Email Count 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 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

Open

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
 One of the API keys associated with your account.

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": "Pro",
    "plan_level": 3,
    "reset_date": 2024-11-16,
    "team_id": 1,
    "calls": {
      "_deprecation_notice": "Sums the searches and the verifications, giving an unprecise look of the requests available",
      "used": 18526,
      "available": 20000
    },
    "requests": {
      "searches": {
        "used": 14260,
        "available": 10000
      },
      "verifications": {
        "used": 4266,
        "available": 10000
      }
    }
  }
}

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, 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, 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 generate 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

Retrieves all the fields of a lead.

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

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

Get my free API key

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

Creates a new lead. The parameters must be passed as a JSON hash.

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 & 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 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.
HTTP request example

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

Get my free API key

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

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.

HTTP request example

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

Get my free API key

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

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.

HTTP request example

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

Get my free API key

Request Body
{
  "company": "Facebook"
}


Response: 204 No Content

Delete a lead

Deletes an existing lead.

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

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

Get my free API key

Response: 204 No Content

Custom Attributes

Saving and managing your custom attributes 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 custom attributes

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
Required
 Your secret API key. You can generate it in your dashboard.
HTTP request example

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

Get my free API key

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

Retrieves all the fields of a custom attribute.

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

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

Get my free API key

Response: 200 OK
{
  "data": {
    "id": 1,
    "label": "Campaign ID",
    "slug": "campaign_id"
  }
}

Create a custom attribute

Creates a new custom attribute. The parameters must be passed as a JSON hash.

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.
HTTP request example

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

Get my free API key

Request Body
{
  "label": "Campaign ID"
}


Response: 201 Created
{
  "data": {
    "id": 1,
    "label": "Campaign ID",
    "slug": "campaign_id"
  }
}

Update a custom attribute

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.

HTTP request example

PUT https://api.hunter.io/v2/leads_custom_attributes/1?api_key=API_KEY

Get my free API key

Request Body
{
  "label": "Outreach Campaign ID"
}


Response: 204 No Content

Delete a custom attribute

Deletes an existing custom attribute.

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

DELETE https://api.hunter.io/v2/leads_custom_attributes/1?api_key=API_KEY

Get my free API key

Response: 204 No Content

Leads Lists

Saving and managing leads lists 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 lists

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 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.
HTTP request example

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

Get my free API key

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

Retrieves all the fields of a leads list.

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.
HTTP request example

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

Get my free API key

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

Creates a new leads list. The parameters must be passed as a JSON hash.

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

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

Get my free API key

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

Updates an existing leads list. The updated values must be passed as a JSON hash.

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

PUT https://api.hunter.io/v2/leads_lists/1?api_key=API_KEY

Get my free API key

Request Body
{
  "name": "New leads list name"
}


Response: 204 No Content

Delete a leads list

Deletes an existing leads list.

id
Required
 Identifier of the leads list.
api_key
Required
 Your secret API key. You can generate it in your dashboard.
HTTP request example

DELETE https://api.hunter.io/v2/leads_lists/1?api_key=API_KEY

Get my free API key

Response: 204 No Content

Campaigns

You can interact with your campaigns 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:

All these calls are free.

List all your campaigns

Returns all the campaigns in your account. The campaigns are returned in reverse-chronological order by creation date.

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.
HTTP request example

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

Get my free API key

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 campaign

Returns all the recipients of a campaign. The recipients are returned in chronological order by addition date.

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.
HTTP request example

GET https://api.hunter.io/v2/campaigns/1/recipients?api_key=API_KEY

Get my free API key

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

Add a recipient to a campaign. 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 campaign with the corresponding reason. The %code reason can be one of:

  • duplicate - email is already added to the campaign
  • invalid - email has invalid format
  • removed - email was already removed from the campaign
  • 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 campaign, the email might be sent shortly after your API call, leaving you no time to cancel the sending in case of a mistake.

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 50 emails.
In case an email doesn't pass our validation, an error is returned, and no recipient is added.
lead_ids
Required*
 The lead IDs you want to add to the campaign. It should be an array of up to 50 lead IDs.
In case a lead cannot be found, an error is returned, and no recipients are added.
api_key
Required
 Your secret API key. You can generate it in your dashboard.

* You must send at least the email(s), lead ID(s) or both.

HTTP request example

POST https://api.hunter.io/v2/campaigns/42/recipients?api_key=API_KEY

Get my free API key

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

Cancel scheduled messages to a recipient from a campaign. The parameters must be passed as a JSON hash.

Only scheduled messages from the provided campaign to the provided recipients will be canceled.

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

DELETE https://api.hunter.io/v2/campaigns/42/recipients?api_key=API_KEY

Get my free API key

Request Body
{
  "emails": ["marcus@hunter.io"]
}


Response: 201 Created
{
  "data": {
    "recipients_canceled": ["marcus@hunter.io"],
    "messages_canceled": 1
  },
  "meta": {
    "params": {
      "emails": ["marcus@hunter.io"]
    }
  }
}

API wrappers

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 to have a new wrapper listed.

You can also integrate Hunter's API in your workflow without writing a line of code with Hunter's Zapier integration.

We use cookies
We use cookies to analyze how Hunter's website is used and personalize your experience. Learn more
Opt-out