Hunter API V2

https://hunter.io/api-documentation/v2
Admin
The Hunter API V2 provides a simple JSON API for email search, verification, lead management,...
Tokens:170,327
Snippets:832
Trust Score:10
Update:2 days ago
Show doc for...
Tokens:
Raw
### Response for GET follow-up

Source: https://hunter.io/api-documentation/v2

Example 200 OK response for the GET follow-up request.

```JSON
{
  "data": {
    "id": 1001,
    "step": 0,
    "wait_days": 0,
    "message_format": "text",
    "messages_sent": 12,
    "subject": "Quick question about {{company}}",
    "body": "Hi {{first_name}}, ...",
    "variant": null
  }
}
```

--------------------------------

### HTTP Request Example for Domains Suggestion

Source: https://hunter.io/api-documentation/v2

Example GET request to the Domains Suggestion endpoint. Requires a query parameter (company name) and an api_key. The query must be between 3 and 100 characters.

```http
GET https://api.hunter.io/v2/domains-suggestion?query=stripe&api_key=API_KEY
```

--------------------------------

### GET company response

Source: https://hunter.io/api-documentation/v2

Example 200 OK response for the GET company request, showing the company data and meta parameters.

```json
{
  "data": {
    "id": 1,
    "domain": "stripe.com",
    "leads_count": 12,
    "created_at": "2026-05-26 12:00:00 UTC"
  },
  "meta": {
    "params": {
      "id": 1
    }
  }
}
```

--------------------------------

### Domain Finder HTTP Request Example

Source: https://hunter.io/api-documentation/v2

Example GET request to the Domain Finder endpoint. The company parameter is required and must be at least 3 characters. The api_key is your secret API key from the dashboard.

```HTTP
GET https://api.hunter.io/v2/domain-finder?company=stripe&api_key=API_KEY
```

--------------------------------

### Domain Search API HTTP request example

Source: https://hunter.io/api-documentation/v2

Example GET request to the Domain Search API endpoint. Replace API_KEY with your actual API key.

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

--------------------------------

### HTTP request example for Lookalikes with domain

Source: https://hunter.io/api-documentation/v2

GET request to the Lookalikes endpoint using the domain parameter. Requires an API key. This call is free.

```http
GET https://api.hunter.io/v2/lookalikes?domain=stripe.com&api_key=API_KEY
```

--------------------------------

### HTTP Request: GET leads_lists/1

Source: https://hunter.io/api-documentation/v2

Example request to retrieve a leads list. The id and api_key parameters are required. The response is a 200 OK with the leads list data.

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

--------------------------------

### Retrieve one folder - Response 200 OK

Source: https://hunter.io/api-documentation/v2

Example response for the get folder endpoint. Returns the folder object with id, name, color, company_lists_count, and created_at.

```json
{
                  "data": {
                    "id": 1,
                    "name": "Q2 prospects",
                    "color": "blue",
                    "company_lists_count": 4,
                    "created_at": "2026-04-12T10:15:00Z"
                  }
                }
```

--------------------------------

### 200 OK response for Get a lead

Source: https://hunter.io/api-documentation/v2

Example response body returned when the request succeeds. Contains all lead fields, including verification status and leads_list details.

```json
{
  "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,
    "department": 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",
    "created_by": 1
  }
}
```

--------------------------------

### List all leads HTTP request

Source: https://hunter.io/api-documentation/v2

Example GET request to the Hunter.io v2 leads endpoint. Replace API_KEY with your actual API key. A successful response returns 200 OK.

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

--------------------------------

### Response: 200 OK for Get Leads List

Source: https://hunter.io/api-documentation/v2

Example JSON response returned by the API when the request succeeds. It includes the leads list details and a meta object with the request parameters.

```json
{
  "data": {
    "id": 1,
    "name": "My leads",
    "leads_count": 10,
    "type": "static",
    "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
    }
  }
}
```

--------------------------------

### GET /v2/account-stats - HTTP request example

Source: https://hunter.io/api-documentation/v2

Retrieves a short profile summary for the account behind the API key. This call is free and does not count against your quota. Replace API_KEY with your secret API key from the dashboard.

```http
GET https://api.hunter.io/v2/account-stats?api_key=API_KEY
```

--------------------------------

### Discover response example

Source: https://hunter.io/api-documentation/v2

Example 200 OK response from the Discover endpoint.

```json
{
  "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",
        ]
      }
    }
  }
}
```

--------------------------------

### GET company tag response

Source: https://hunter.io/api-documentation/v2

Example 200 OK response for the GET company tag request.

```json
{
  "data": {
    "id": 1,
    "name": "Partner",
    "color": "3489F9",
    "created_at": "2026-05-26 12:00:00 UTC"
  }
}
```

--------------------------------

### List all folders - Response 200 OK

Source: https://hunter.io/api-documentation/v2

Example response for the list folders endpoint. Shows a folder object with id, name, color, company_lists_count, and created_at, plus meta with total and params.

```json
{
                  "data": {
                    "folders": [
                      {
                        "id": 1,
                        "name": "Q2 prospects",
                        "color": "blue",
                        "company_lists_count": 4,
                        "created_at": "2026-04-12T10:15:00Z"
                      }
                    ]
                  },
                  "meta": {
                    "total": 1,
                    "params": { "limit": 20, "offset": 0 }
                  }
                }
```

--------------------------------

### GET /v2/messages (Filter example)

Source: https://hunter.io/api-documentation/v2

Example of using the Messages endpoint with multiple filters: status=sent,opened, sequence_id=42, and replied=true.

```APIDOC
## [GET] /v2/messages (Filter example)

### Description
Example of using the Messages endpoint with multiple filters: status=sent,opened, sequence_id=42, and replied=true.

### Method
GET

### Endpoint
https://api.hunter.io/v2/messages

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your secret API key.
- **status** (string) - Optional - Filter on one or more delivery statuses. Pass a comma-separated list to combine values. Allowed values: `pending`, `error`, `sent`, `bounced`, `opened`, `clicked`, `replied`, `reply`, `unsubscribed`, `canceled`, `successful`.
- **sequence_id** (string) - Optional - Restrict the response to messages from a given sequence (campaign). `campaign_id` is accepted as an alias.
- **replied** (boolean) - Optional - `true` or `false`. Filters on whether the message received a reply.

### Request Example
GET https://api.hunter.io/v2/messages?status=sent,opened&sequence_id=42&replied=true&api_key=API_KEY

### Response
#### Success Response (200)
(No explicit response example provided in the source.)
```

--------------------------------

### Create API key - Response 201 Created

Source: https://hunter.io/api-documentation/v2

Example response after creating an API key. The full token is returned only once, so store it safely.

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "name": "CI server",
    "token": "0123456789abcdef0123456789abcdef01234567",
    "created_at": "2024-01-03T09:00:00Z"
  }
}
```

--------------------------------

### List all folders - 200 OK response

Source: https://hunter.io/api-documentation/v2

Example JSON response for the list folders endpoint. Shows folder fields including id, name, color, leads_lists_count, and created_at.

```json
{
                  "data": {
                    "folders": [
                      {
                        "id": 1,
                        "name": "Q2 prospects",
                        "color": "374151",
                        "leads_lists_count": 4,
                        "created_at": "2026-04-12T10:15:00Z"
                      }
                    ]
                  },
                  "meta": {
                    "total": 1,
                    "params": { "limit": 20, "offset": 0 }
                  }
                }
```

--------------------------------

### Get a company list - 200 OK response

Source: https://hunter.io/api-documentation/v2

Example JSON response for the get company list endpoint. Includes companies_count field.

```json
{
  "data": {
    "id": 1,
    "name": "My static list",
    "type": "static",
    "companies_count": 10,
    "company_list_folder_id": null,
    "created_at": "2026-03-18T19:00:00Z"
  }
}
```

--------------------------------

### Create a company list: Response 201 Created

Source: https://hunter.io/api-documentation/v2

Example response when a company list is successfully created.

```json
{
  "data": {
    "id": 3,
    "name": "My new company list",
    "type": "static",
    "companies_count": 0,
    "company_list_folder_id": null,
    "created_at": "2026-03-18T19:00:00Z"
  }
}
```

--------------------------------

### Response for removing recipients from a started sequence

Source: https://hunter.io/api-documentation/v2

Example response with 201 Created status. Shows recipients_canceled and messages_canceled for a started sequence, and skipped_recipients is null.

```json
{
  "data": {
    "recipients_removed": [],
    "recipients_canceled": ["marcus@hunter.io"],
    "messages_canceled": 1,
    "skipped_recipients": null
  },
  "meta": {
    "params": {
      "emails": ["marcus@hunter.io"]
    }
  }
}
```

--------------------------------

### Create a new folder - Response 201 Created

Source: https://hunter.io/api-documentation/v2

Example response body for the create folder request, showing the created folder object with id, name, color, leads_lists_count, and created_at.

```json
{
  "data": {
    "id": 1,
    "name": "Q2 prospects",
    "color": "374151",
    "leads_lists_count": 0,
    "created_at": "2026-04-12T10:15:00Z"
  }
}
```

--------------------------------

### Get a webhook - Response 200 OK

Source: https://hunter.io/api-documentation/v2

Example JSON response for the get webhook endpoint. Returns a single webhook object with id, target_url, and event.

```json
{
  "status": "success",
  "data": {
    "id": 1,
    "target_url": "https://example.com/hooks/leads",
    "event": "lead.created"
  }
}
```

--------------------------------

### Create a new folder - HTTP request example

Source: https://hunter.io/api-documentation/v2

POST request to create a new folder. Requires name, color, and api_key parameters. Returns 201 Created with folder data.

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

--------------------------------

### Create a new folder - Response 201 Created

Source: https://hunter.io/api-documentation/v2

Example response for the create folder endpoint. Returns the created folder object with id, name, color, company_lists_count (0), and created_at.

```json
{
                  "data": {
                    "id": 1,
                    "name": "Q2 prospects",
                    "color": "blue",
                    "company_lists_count": 0,
                    "created_at": "2026-04-12T10:15:00Z"
                  }
                }
```

--------------------------------

### GET request to retrieve a lead

Source: https://hunter.io/api-documentation/v2

HTTP request example for the Get a lead endpoint. Requires the lead id and your secret API key as query parameters.

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

--------------------------------

### Email Verifier API HTTP Request Example

Source: https://hunter.io/api-documentation/v2

Example GET request to the Email Verifier API endpoint. Replace API_KEY with your actual API key.

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

--------------------------------

### Domain Finder Response Example (200 OK)

Source: https://hunter.io/api-documentation/v2

Example JSON response from the Domain Finder endpoint. Shows the resolved domain, company name, logo URL, and email count, along with meta information including the parameters used.

```JSON
{
                "data": [
                  {
                    "domain": "stripe.com",
                    "company_name": "Stripe",
                    "logo": "https://logos.hunter.io/stripe.com",
                    "email_count": 281
                  }
                ],
                "meta": {
                  "results": 1,
                  "params": {
                    "company": "stripe",
                    "limit": 5,
                    "perfect_match": false
                  }
                }
              }
```

--------------------------------

### List all leads lists - Response 200 OK

Source: https://hunter.io/api-documentation/v2

Example response for a successful request. Shows the structure of the returned data, including list details and meta information.

```JSON
{
  "data": {
    "leads_lists": [
      {
        "id": 1,
        "name": "My first list",
        "leads_count": 10,
        "type": "static",
        "created_at": "2021-01-01 12:00:00 UTC"
      },
      {
        "id": 2,
        "name": "My second list",
        "leads_count": 1,
        "type": "static",
        "created_at": "2021-01-01 12:00:01 UTC"
      },
    }
  },
  "meta": {
    "total": 2,
    "params": {
      "limit": 20,
      "offset": 0
    }
  }
}
```

--------------------------------

### Usage response 200 OK

Source: https://hunter.io/api-documentation/v2

Example response showing usage data with reset date and request counts.

```json
{
  "data": {
    "reset_date": 2026-10-27,
    "requests": {
      "searches": {
        "used": 500,
        "available": 10000,
        "remaining": 9500
      },
      "verifications": {
        "used": 100,
        "available": 20000,
        "remaining": 19900
      }
    }
  }
}
```

--------------------------------

### List all lead tags - Response 200 OK

Source: https://hunter.io/api-documentation/v2

Example JSON response for the list tags request, showing tag objects with id, name, color, and created_at, plus meta information.

```json
{
  "data": {
    "tags": [
      {
        "id": 1,
        "name": "Prospect",
        "color": "3489F9",
        "created_at": "2026-05-26 12:00:00 UTC"
      },
      {
        "id": 2,
        "name": "Important",
        "color": "10B981",
        "created_at": "2026-05-26 12:00:01 UTC"
      }
    ]
  },
  "meta": {
    "total": 2,
    "params": { "limit": 25, "offset": 0 }
  }
}
```

--------------------------------

### Discover People HTTP request example

Source: https://hunter.io/api-documentation/v2

GET request to the Discover People endpoint with an industry filter.

```http
GET https://api.hunter.io/v2/discover/people?api_key=API_KEY&industry[include][]=Financial Services
```

--------------------------------

### Filter example - GET https://api.hunter.io/v2/messages?status=sent,opened&sequence_id=42&replied=true&api_key=API_KEY

Source: https://hunter.io/api-documentation/v2

Example request using multiple optional filters: status, sequence_id, and replied. Filters are combinable and narrow results to messages matching all of them.

```HTTP
GET https://api.hunter.io/v2/messages?status=sent,opened&sequence_id=42&replied=true&api_key=API_KEY
```

--------------------------------

### Response: 200 OK for List Follow-ups

Source: https://hunter.io/api-documentation/v2

Example JSON response showing follow-ups with fields like id, step, wait_days, message_format, messages_sent, subject, body, and variant. Includes meta with limit and offset.

```json
{
  "data": {
    "follow_ups": [
      {
        "id": 1001,
        "step": 0,
        "wait_days": 0,
        "message_format": "text",
        "messages_sent": 12,
        "subject": "Quick question about {{company}}",
        "body": "Hi {{first_name}}, ...",
        "variant": null
      },
      {
        "id": 1002,
        "step": 1,
        "wait_days": 3,
        "message_format": "text",
        "messages_sent": 8,
        "subject": "Re: Quick question about {{company}}",
        "body": "Just checking in ...",
        "variant": null
      }
    ]
  },
  "meta": {
    "limit": 20,
    "offset": 0
  }
}
```

--------------------------------

### List companies HTTP request

Source: https://hunter.io/api-documentation/v2

Example GET request to list companies. Requires an API key, which can be generated in the dashboard.

```http
GET https://api.hunter.io/v2/companies?api_key=API_KEY
```

--------------------------------

### GET request to retrieve sequence stats

Source: https://hunter.io/api-documentation/v2

HTTP request example for retrieving sequence statistics. Requires sequence id and api_key.

```http
GET https://api.hunter.io/v2/sequences/42/stats?api_key=API_KEY
```

--------------------------------

### POST /v2/leads_lists/folders

Source: https://hunter.io/api-documentation/v2

Creates a new folder on the requesting user's team. Requires a name, color, and API key. Returns 201 Created with the folder details.

```APIDOC
## [POST] /v2/leads_lists/folders

### Description
Creates a new folder on the requesting user's team.

### Method
POST

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

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your secret API key. You can retrieve it in your dashboard.

#### Request Body
- **name** (string) - Required - Display name of the folder.
- **color** (string) - Required - Color of the folder shown in the web app sidebar. Must be one of the supported hex values: `374151`, `3489F9`, `10B981`, `F5BA0B`, `EF4444`, `7C3AED`, `F97316`, `E5E7EB`, `B4D9F7`, `BAE6B0`, `FDE68A`, `FBD0D0`, `D4C4F8`, `FFD79B`.

### Request Example
```
POST https://api.hunter.io/v2/leads_lists/folders?api_key=API_KEY
```

### Response
#### Success Response (201 Created)
- **data** (object) - The created folder object.
  - **id** (integer) - Folder identifier.
  - **name** (string) - Display name of the folder.
  - **color** (string) - Color of the folder.
  - **leads_lists_count** (integer) - Number of leads lists in the folder.
  - **created_at** (string) - Creation timestamp in ISO 8601 format.

#### Response Example
```
{
  "data": {
    "id": 1,
    "name": "Q2 prospects",
    "color": "374151",
    "leads_lists_count": 0,
    "created_at": "2026-04-12T10:15:00Z"
  }
}
```
```

--------------------------------

### Combined Enrichment HTTP request example

Source: https://hunter.io/api-documentation/v2

GET request to the Combined Enrichment endpoint. Replace API_KEY with your actual API key from the dashboard.

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

--------------------------------

### Usage history response example

Source: https://hunter.io/api-documentation/v2

Example JSON response with status 200 OK. Shows a single usage record with details such as type, product, source, credits, and request information.

```json
{
  "data": [
    {
      "id": 987654,
      "type": "search",
      "product": "domain_search",
      "source": "api",
      "credits": 1,
      "free": false,
      "made_at": "2026-10-19T12:10:43Z",
      "made_by": {
        "id": 12345,
        "first_name": "Jane",
        "last_name": "Doe",
        "api_key_name": "Production key"
      },
      "request": {
        "url": "https://api.hunter.io/v2/domain-search?domain=stripe.com",
        "ip": "203.0.113.42",
        "user_agent": "Hunter Ruby client",
        "filters": null,
        "bulk_search_id": null,
        "bulk_finder_id": null
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}
```

--------------------------------

### Email Finder HTTP Request

Source: https://hunter.io/api-documentation/v2

Example GET request to the Email Finder endpoint using domain, first_name, last_name, and api_key parameters.

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