image/svg+xml


Back to Hunter

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 guesses the most likely email of a person using his/her first name, last name and a domain 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.

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.

Log in to get your API key.

Errors

Hunter's API uses conventional HTTP response codes to indicate the success or failure of an API request.

In case of an error, we'll return 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.
401 - Unauthorized No valid API key was provided.
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 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.
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.

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.

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

HTTP request example
GET https://api.hunter.io/v2/domain-search?domain=stripe.com
Response: 200 OK
  {
    "data" : {
      "domain" : "intercom.io",
      "webmail" : false,
      "pattern" : "{first}",
      "organization" : "Intercom",
      "emails" : [
        {
          "value": "ciaran@intercom.io",
          "type": "personal",
          "confidence": 92,
          "sources": [
            {
              "domain" : "github.com",
              "uri" : "http://github.com/ciaranlee",
              "extracted_on" : "2015-07-29"
            },
            {
              "domain" : "blog.intercom.io",
              "uri" : "http://blog.intercom.io/were-hiring-a-support-engineer/",
              "extracted_on" : "2015-08-29"
            }
          ],
          "first_name" : "Ciaran",
          "last_name" : "Lee",
          "position" : "Support Engineer",
          "linkedin" : null,
          "twitter" : "ciaran_lee",
          "phone_number" : null,
        },
        ...
      }
    },
    "meta" : {
      "results" : 35,
      "limit" : 10,
      "offset" : 0,
      "params" : {
        "domain" : "intercom.io",
        "company" : null,
        "type" : null,
        "offset" : "0"
      }
    }
  }

Email Finder

This API endpoint generates 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, "asana.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.
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 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 lowercase.
api_key
Required
 Your secret API key. You can generate it in your dashboard.

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

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

HTTP request example
GET https://api.hunter.io/v2/email-finder?domain=asana.com&first_name=Dustin&last_name=Moskovitz
HTTP request example with the company and full_name params
GET https://api.hunter.io/v2/email-finder?company=Asana&full_name=Dustin+Moskovitz
Response: 200 OK
  {
    "data" : {
      "email": "dustin@asana.com",
      "score": 72,
      "domain": "asana.com",
      "sources": [
        {
          "domain" : "blog.asana.com",
          "uri" : "http://blog.asana.com",
          "extracted_on" : "2015-09-27"
        }
      ],
    },
    "meta" : {
      "params" : {
        "first_name" : "Dustin",
        "last_name" : "Moskovitz",
        "domain" : "asana.com",
        "company" : null
      }
    }
  }

Email Verifier

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

Hunter focuses on B2B. Therefore, webmails are not verified. We'll run every check but won't reach the remote SMTP server.

This endpoint is rate-limited by domain name. You can check up to 200 email addresses for a domain name every 24 hours. You can check the number of requests remaining using the X-RateLimit-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.

score is the deliverability score we give to the email address.

regexp is true if the email addresses pass 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 exists 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 server accept all the email addresses. It mean you can have have false positives on SMTP checks.

sources If we have found the given email address somewhere on he web, we display the sources here. The number of sources is limited to 20.

HTTP request example
GET https://api.hunter.io/v2/email-verifier?email=steli@close.io
Response: 200 OK
  {
    "data" : {
      "result": "deliverable",
      "score": 91,
      "regexp": true,
      "gibberish": false,
      "disposable": false,
      "webmail": false,
      "mx_records": true,
      "smtp_server": true,
      "smtp_check": true,
      "accept_all": false,
      "sources": [
        {
          "domain": "blog.close.io",
          "uri": "http://blog.close.io/how-to-become-great-at-sales",
          "extracted_on": "2015-01-26"
        },
        {
          "domain": "blog.close.io",
          "uri": "http://blog.close.io/how-to-do-referral-sales",
          "extracted_on": "2015-01-26"
        }
      ]
    },
    "meta" : {
      "params" : {
        "email" : "steli@close.io"
      }
    }
  }

Email Count

This API endpoint allows you to know how many email addresses we have for one domain. 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.

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.

HTTP request example
GET https://api.hunter.io/v2/email-count?domain=stripe.com
Response: 200 OK
  {
    "data" : {
      "total" : 81,
      "personal_emails" : 65,
      "generic_emails" : 16
    },
    "meta" : {
      "params" : {
        "domain" : "stripe.com"
      }
    }
  }

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.
HTTP request example
GET https://api.hunter.io/v2/account
Response: 200 OK
  {
    "data" : {
      "first_name" : "Antoine",
      "last_name" : "Finkelstein",
      "email" : "antoine@hunter.io",
      "plan_name" : "Pro",
      "plan_level" : 4,
      "reset_date" : 2017-05-29,
      "team_id" : 1,
      "calls" : {
        "used" : 28526,
        "available" : 50000
      }
    }
  }

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 optional parameters can be combined to filter the results.

offset The number of leads to skip. Use this parameter to fetch all the leads.
limit A limit on the number of leads to be returned. Limit can range between 1 and 100 leads. Default is 20.
lead_list_id Only returns the leads belonging to this list.
first_name Only returns the leads with this first name.
last_name Only returns the leads with this last name.
email Only returns the leads with this email.
company Only returns the leads with this company.
phone_number Only returns the leads with this phone number.
twitter Only returns the leads with this Twitter handle.
api_key
Required
 Your secret API key. You can generate it in your dashboard.
HTTP request example
GET https://api.hunter.io/v2/leads
Response: 200 OK
{
  "data" : {
    "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,
        "postal_code": null,
        "source": null,
        "linkedin_url": null,
        "phone_number": null,
        "twitter": null,
        "leads_list": {
          "id": 1,
          "name": "My leads list",
          "leads_count": 2,
          "team_id": null
        }
      },
      {
        "id": 2,
        "first_name": "Dustin",
        "last_name": "Moskovitz",
        "position": "CEO",
        "company": "Asana",
        "company_industry": null,
        "company_size": null,
        "email": "dustin@asana.com",
        "confidence_score": null,
        "website": "https://asana.com",
        "country_code": "US",
        "postal_code": null,
        "source": null,
        "linkedin_url": null,
        "phone_number": null,
        "twitter": "moskov",
        "leads_list": {
          "id": 1,
          "name": "My leads list",
          "leads_count": 2,
          "team_id": null
        }
      }
    }
  },
  "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
Response: 200 OK
{
  "data" : {
    "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,
    "postal_code": null,
    "source": null,
    "linkedin_url": null,
    "phone_number": null,
    "twitter": null,
    "leads_list": {
      "id": 1,
      "name": "My leads list",
      "leads_count": 2,
      "team_id": null
    }
  }
}

Create a lead

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

first_name
Required
 The first name of the leads.
last_name
Required
 The last name of the lead.
email The email address 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.
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 website of the company.
country_code The country of the lead. The country code is defined in the ISO 3166-1 alpha-2 standard.
postal_code The postal code or ZIP code of the lead.
source The source where the lead has been found.
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.
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.
api_key
Required
 Your secret API key. You can generate it in your dashboard.
HTTP request example
POST https://api.hunter.io/v2/leads
Request Body
{
  "first_name": "Dustin",
  "last_name": "Moskovitz",
  "position": "Co-founder",
  "company": "Asana",
  "company_industry": "Internet",
  "company_size": "201-500 employees",
  "email": "dustin@asana.com",
  "confidence_score": 95,
  "website": "https://asana.com/",
  "phone_number": "720-555-6251",
  "twitter": "moskov"
}
Response: 201 Created
{
  "data": {
    "id": 3,
    "first_name": "Dustin",
    "last_name": "Moskovitz",
    "position": "Co-founder",
    "company": "Asana",
    "company_industry": "Internet",
    "company_size": "201-500 employees",
    "email": "dustin@asana.com",
    "confidence_score": 95,
    "website": "https://asana.com/",
    "country_code": "US",
    "postal_code": null,
    "source": null,
    "linkedin_url": null,
    "phone_number": "720-555-6251",
    "twitter": "moskov",
    "leads_list": {
      "id": 1,
      "name": "My leads list",
      "leads_count": 3,
      "team_id": null
    }
  }
}

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

offset The number of lists to skip. Use this parameter to fetch all the lists.
limit A limit on the number of lists to be returned. Limit can range between 1 and 100 lists. Default is 20.
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
Response: 200 OK
{
  "data" : {
    "leads_lists" : [
      {
        "id": 1,
        "name": "My first list",
        "leads_count": 10,
        "team_id": null
      },
      {
        "id": 2,
        "name": "My second list",
        "leads_count": 1,
        "team_id": 1
      },
    }
  },
  "meta" : {
    "total" : 2
  }
}

Get a leads list

Retrieves all the fields of a 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
GET https://api.hunter.io/v2/leads_lists/1
Response: 200 OK
{
  "data" : {
    "name": "My leads",
    "leads_count": 10,
    "team_id": null,
    "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,
        "postal_code": null,
        "source": null,
        "linkedin_url": null,
        "phone_number": null,
        "twitter": null,
        "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.
team_id The id of the team to share your leads with (must be your team).
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
Request Body
{
  "name": "My new leads list"
}
Response: 201 Created
{
  "data": {
    "list_id": 3,
    "name": "My new leads list",
    "team_id": null
  }
}

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.
team_id The id of the team to share your leads with (must be your team).
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
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
Response: 204 No Content