# [Introduction](/content/api-documentation\#introduction/index.html)
You can enjoy our service's features with our simple JSON API:
- [Discover](/content/api-documentation#discover/index.html)
returns companies matching a set of criteria.
- The
[Domain Search](/content/api-documentation#domain-search/index.html)
returns all the email addresses found using one given domain
name, with sources.
- The
[Email Finder](/content/api-documentation#email-finder/index.html)
finds the most likely email address from a domain name, a first
name and a last name.
- The
[Email Verifier](/content/api-documentation#email-verifier/index.html)
checks the deliverability of a given email address, verifies if
it has been found in our database, and returns their sources.
- The
[Enrichment](/content/api-documentation#enrichment/index.html)
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:
- The
[Leads](/content/api-documentation#leads/index.html)
- The
[Custom Attributes](/content/api-documentation#custom-attributes/index.html)
- The
[Leads Lists](/content/api-documentation#leads-lists/index.html)
- The
[Email Sequences](/content/api-documentation#campaigns/index.html)
API endpoint
```
https://api.hunter.io/v2/
```
# [Structure](/content/api-documentation\#structure/index.html)
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](/content/api-documentation#errors/index.html).
Successful response
```
{
"data": {
...
},
"meta": {
...
}
}
```
Error response
```
{
"errors": {
...
}
}
```
# [Authentication](/content/api-documentation\#authentication/index.html)
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](/content/api-keys/index.html).
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](/content/api-documentation#domain-search/index.html), the
[Email Finder](/content/api-documentation#email-finder/index.html), and the
[Email Verifier](/content/api-documentation#email-verifier/index.html).
[Sign up](/content/users/sign_up?from=api/index.html)
to get your free API key.
# [Errors](/content/api-documentation\#errors/index.html)
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](/content/api-documentation\#discover/index.html)
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](/content/api-documentation#domain-search/index.html)
, or you can get more information about the companies using
[Company Enrichment.](/content/api-documentation#company-enrichment/index.html)
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:
```
{
"headquarters_location": {
"include": [
{ "city": "Paris", "country": "FR" }
]
}
}
``` |
| **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](/content/files/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](/content/files/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](/content/api-keys/index.html). |
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](/content/api-documentation#errors/index.html).
| | |
| --- | --- |
| **400**`invalid_company_type` | One of the supplied `company_type` values is invalid. |
| **400**`invalid_funding` | One of the supplied `funding` input is invalid. |
| **400**`invalid_funding_series` | One of the supplied `funding[series]` values is invalid. |
| **400**`invalid_funding_date_from` | The supplied `funding[date][from]` is invalid. |
| **400**`invalid_funding_date_to` | The supplied `funding[date][to]` is invalid. |
| **400**`invalid_funding_date_range` | The `funding[date][from]` must be before the `funding[date][to]`. |
| **400**`invalid_funding_amount_from` | The supplied `funding[amount][from]` is invalid. |
| **400**`invalid_funding_amount_to` | The supplied `funding[amount][to]` is invalid. |
| **400**`invalid_funding_amount_range` | The `funding[amount][to]` must be greater than the `funding[amount][from]`. |
| **400**`invalid_headcount` | One of the supplied `headcount` values is invalid. |
| **400**`invalid_headquarters_location` | The supplied `headquarters_location` input is not valid. |
| **400**`invalid_headquarters_location_include_combination` | The combination of values in a `headquarters_location[include]` value is invalid. |
| **400**`invalid_headquarters_location_include_business_region` | The `headquarters_location[include][business_region]` value is invalid. |
| **400**`invalid_headquarters_location_include_continent` | The `headquarters_location[include][continent]` value is invalid. |
| **400**`invalid_headquarters_location_include_country` | The `headquarters_location[include][country]` value is invalid. |
| **400**`invalid_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. |
| **400**`invalid_headquarters_location_exclude_combination` | The combination of values in a `headquarters_location[exclude]` value is invalid. |
| **400**`invalid_headquarters_location_exclude_business_region` | The `headquarters_location[exclude][business_region]` value is invalid. |
| **400**`invalid_headquarters_location_exclude_continent` | The `headquarters_location[exclude][continent]` value is invalid. |
| **400**`invalid_headquarters_location_exclude_country` | The `headquarters_location[exclude][country]` value is invalid. |
| **400**`invalid_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 |
| **400**`invalid_industry` | One of the supplied `industry` values is invalid. |
| **400**`invalid_keywords` | The supplied `keywords` input is not valid. |
| **400**`invalid_keywords_match` | The value in the `keywords[match]` field must be either `any` or `all`. |
| **400**`invalid_technology` | One of the supplied `technology` values is invalid. |
| **400**`invalid_technology_match` | The value in the `technology[match]` field must be either `any` or `all`.. |
| **400**`invalid_year_founded_combination` | The combination of fields used in `year_founded` is invalid. |
| **400**`invalid_year_founded_include` | One of the values supplied in `year_founded[include]` is invalid. |
| **400**`invalid_year_founded_from` | The supplied `year_founded[from]` value is invalid. |
| **400**`invalid_year_founded_to` | The supplied `year_founded[to]` value is invalid. |
| **400**`pagination_error` | The supplied `limit` or `offset` is invalid.
This error can also be returned when changing the default values for a Free plan user. |
| **403**`no_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](/content/users/sign_up?from=api/index.html)
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](/content/api-documentation\#domain-search/index.html)
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:
```
{
"location": {
"include": [
{ "city": "Paris", "country": "FR" }
]
}
}
```
**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](/content/api-keys/index.html). |
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](/content/api-documentation#errors/index.html).
| | |
| --- | --- |
| **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](/content/users/sign_up?from=api/index.html)
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](/content/api-documentation\#email-finder/index.html)
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](/content/api-keys/index.html). |
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](/content/api-documentation#errors/index.html).
| | |
| --- | --- |
| **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](/content/users/sign_up?from=api/index.html)
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](/content/api-documentation\#email-verifier/index.html)
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](/content/api-keys/index.html). |
`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](/content/api-documentation#errors/index.html).
| | |
| --- | --- |
| **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](/content/users/sign_up?from=api/index.html)
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](/content/api-documentation\#enrichment/index.html)
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](/content/api-documentation#email-enrichment/index.html)
- [Company Enrichment](/content/api-documentation#company-enrichment/index.html)
- [Combined Enrichment](/content/api-documentation#combined-enrichment/index.html)
## [Email Enrichment](/content/api-documentation\#email-enrichment/index.html)
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](/content/api-keys/index.html). |
| **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](/content/users/sign_up?from=api/index.html)
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](/content/api-documentation\#company-enrichment/index.html)
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](/content/api-keys/index.html). |
| **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](/content/users/sign_up?from=api/index.html)
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](/content/api-documentation\#combined-enrichment/index.html)
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](/content/api-keys/index.html). |
| **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](/content/users/sign_up?from=api/index.html)
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](/content/api-documentation\#email-count/index.html)
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](/content/api-keys/index.html). |
| **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](/content/api-documentation#errors/index.html).
| | |
| --- | --- |
| **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](/content/users/sign_up?from=api/index.html)
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](/content/api-documentation\#account/index.html)
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](/content/api-keys/index.html). |
`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](/content/users/sign_up?from=api/index.html)
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](/content/api-documentation\#leads/index.html)
Saving and managing leads in Hunter can be done entirely
through the RESTful API.
Here is the list of the available methods:
- [List all your leads](/content/api-documentation#list-leads/index.html)
- [Retrieve one of your leads](/content/api-documentation#get-lead/index.html)
- [Create a new lead](/content/api-documentation#create-lead/index.html)
- [Create or update a lead](/content/api-documentation#upsert-lead/index.html)
- [Update an existing lead](/content/api-documentation#update-lead/index.html)
- [Delete an existing lead](/content/api-documentation#delete-lead/index.html)
All these calls are free.
## [List all your leads](/content/api-documentation\#list-leads/index.html)
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](/content/api-keys/index.html). |
HTTP request example
```
GET https://api.hunter.io/v2/leads?api_key=API_KEY
```
[Get my free API key](/content/users/sign_up?from=api/index.html)
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**
required | Identifier of the lead. |\
| **api\_key**
required | Your secret API key. You can retrieve it in your
[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**
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](/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
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. |\
| **leads\_list\_ids** | The identifiers of the lists 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 retrieve it in your
[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**
required | Identifier of the lead. |\
| **api\_key**
required | Your secret API key. You can retrieve it in your
[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**
required | Your secret API key. You can retrieve it in your
[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**
required | Identifier of the custom attribute. |\
| **api\_key**
required | Your secret API key. You can retrieve it in your
[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**
required | The name, or label, of your custom attribute. Has to be unique. |\
| **api\_key**
required | Your secret API key. You can retrieve it in your
[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**
required | Identifier of the custom attribute. |\
| **api\_key**
required | Your secret API key. You can retrieve it in your
[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
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](/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**
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 retrieve it in your
[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**
required | The name of the leads list. |\
| **api\_key**
required | Your secret API key. You can retrieve it in your
[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**
required | The name of the leads list. |\
| **api\_key**
required | Your secret API key. You can retrieve it in your
[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**
required | Identifier of the leads list. |\
| **api\_key**
required | Your secret API key. You can retrieve it in your
[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
between 1 and 100 sequences. Default is 20. |\
| **offset** | The number of sequences to skip. Use this parameter to fetch all
the sequences. |\
| **api\_key**
required | Your secret API key. You can retrieve it in your
[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
between 1 and 100 sequences. Default is 20. |\
| **offset** | The number of sequences to skip. Use this parameter to fetch all
the sequences. |\
| **api\_key**
required | Your secret API key. You can retrieve it in your
[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**
required | Identifier of the sequence |\
| **emails**
required unless lead\_ids | The recipients you want to add to the sequence. 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 unless emails | The lead IDs you want to add to the sequence. 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 retrieve it in your
[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**
required | Identifier of the sequence |\
| **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 retrieve it in your
[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**
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**
required | The domain name of the company for which you want to get the logo.
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
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