Hunter

Hunter Lists API

The Lists API from Hunter — 20 operation(s) for lists.

GitHub OpenAPI

Operations 47

GET /leads_lists List lead lists #
POST /leads_lists Create a lead list #
GET /leads_lists/{id} Get a lead list #
PATCH /leads_lists/{id} Update a lead list #
PUT /leads_lists/{id} Replace a lead list #
DELETE /leads_lists/{id} Delete a lead list #
GET /leads_lists/folders List lead list folders #
POST /leads_lists/folders Create a lead list folder #
GET /leads_lists/folders/{id} Get a lead list folder #
PATCH /leads_lists/folders/{id} Update a lead list folder #
PUT /leads_lists/folders/{id} Replace a lead list folder #
DELETE /leads_lists/folders/{id} Delete a lead list folder #
POST /leads_lists/{id}/favorite Favorite a lead list #
DELETE /leads_lists/{id}/favorite Unfavorite a lead list #
POST /leads_lists/{id}/merge Merge lead lists #
GET /leads-lists List lead lists (hyphen alias) #
POST /leads-lists Create a lead list (hyphen alias) #
GET /leads-lists/{id} Get a lead list (hyphen alias) #
PATCH /leads-lists/{id} Update a lead list (hyphen alias) #
PUT /leads-lists/{id} Replace a lead list (hyphen alias) #
DELETE /leads-lists/{id} Delete a lead list (hyphen alias) #
GET /leads-lists/folders List lead list folders (hyphen alias) #
POST /leads-lists/folders Create a lead list folder (hyphen alias) #
GET /leads-lists/folders/{id} Get a lead list folder (hyphen alias) #
PATCH /leads-lists/folders/{id} Update a lead list folder (hyphen alias) #
PUT /leads-lists/folders/{id} Replace a lead list folder (hyphen alias) #
DELETE /leads-lists/folders/{id} Delete a lead list folder (hyphen alias) #
POST /leads-lists/{id}/favorite Favorite a lead list (hyphen alias) #
DELETE /leads-lists/{id}/favorite Unfavorite a lead list (hyphen alias) #
POST /leads-lists/{id}/merge Merge lead lists (hyphen alias) #
GET /company-lists List company lists #
POST /company-lists Create a company list #
GET /company-lists/{id} Get a company list #
PATCH /company-lists/{id} Update a company list #
PUT /company-lists/{id} Replace a company list #
DELETE /company-lists/{id} Delete a company list #
GET /company-lists/folders List company list folders #
POST /company-lists/folders Create a company list folder #
GET /company-lists/folders/{id} Get a company list folder #
PATCH /company-lists/folders/{id} Update a company list folder #
PUT /company-lists/folders/{id} Replace a company list folder #
DELETE /company-lists/folders/{id} Delete a company list folder #
POST /company-lists/{id}/favorite Favorite a company list #
DELETE /company-lists/{id}/favorite Unfavorite a company list #
POST /company-lists/{id}/companies Add a company to a company list #
DELETE /company-lists/{id}/companies/{company_id} Remove a company from a company list #
GET /lookalikes Find lookalike companies from a company list or a domain #

Documentation

📖
Documentation
https://hunter.io/api-documentation/v2#domain-search
📖
Documentation
https://hunter.io/api-documentation/v2#email-finder
📖
Documentation
https://hunter.io/api-documentation/v2#email-verifier
📖
Documentation
https://hunter.io/api-documentation/v2#email-count
📖
Documentation
https://hunter.io/api-documentation/v2#account
📖
Documentation
https://hunter.io/api-documentation/v2#discover
📖
Documentation
https://hunter.io/api-documentation/v2#email-enrichment
📖
Documentation
https://hunter.io/api-documentation/v2#company-enrichment
📖
Documentation
https://hunter.io/api-documentation/v2#combined-enrichment
📖
Documentation
https://hunter.io/api-documentation/v2#leads
📖
Documentation
https://hunter.io/api-documentation/v2#leads_lists
📖
Documentation
https://hunter.io/api-documentation/v2#campaigns
📖
Documentation
https://hunter.io/api-documentation/v2#logo

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/hunter/refs/heads/main/openapi/hunter-lists-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/hunter/refs/heads/main/json-schema/hunter-lead-schema.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/hunter/refs/heads/main/json-ld/hunter-context.jsonld

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/hunter:hunter-lists-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

hunter-lists-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Hunter Lists API
  version: 2.0.0
  description: 'Find and verify professional email addresses and manage Hunter resources.

    Hunter''s own MCP servers forward the calling AI client''s User-Agent in a reserved `X-MCP-USER-AGENT` request header. It is read only for usage attribution and to record which AI clients an account has connected from, and never changes a response. Per-request attribution resolves it to a fixed list of known clients; the first call from each new client also stores the User-Agent as sent, so a client Hunter does not yet recognise can be identified. There is nothing for an integration to send here.

    Hunter''s MCP servers also identify themselves with `X-SOURCE: hunter-mcp` or `X-SOURCE: hunter-chatgpt`. These reserved markers attribute server-side actions to the MCP channel, separately from ordinary API and product usage. They do not replace API authentication. Ordinary API clients do not need to send these markers.'
  contact:
    name: Hunter Support
    url: https://help.hunter.io
servers:
- url: https://api.hunter.io/v2
  description: Production
security:
- apiKeyQuery: []
- apiKeyHeader: []
- bearerAuth: []
tags:
- name: Lists
paths:
  /leads_lists:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: listLeadLists
      summary: List lead lists
      tags:
      - Lists
      responses:
        '200':
          description: List lead lists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: createLeadList
      summary: Create a lead list
      tags:
      - Lists
      responses:
        '201':
          description: Create a lead list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads_lists/{id}:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getLeadList
      summary: Get a lead list
      description: 'When the person behind a lead has asked Hunter to delete their address, with a claim or a California DROP request, the lead is returned without it: `email`, `confidence_score`, `verification.date` and `verification.status` are null (HUN-23599).'
      tags:
      - Lists
      responses:
        '200':
          description: Get a lead list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateLeadList
      summary: Update a lead list
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    put:
      operationId: replaceLeadList
      summary: Replace a lead list
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: deleteLeadList
      summary: Delete a lead list
      tags:
      - Lists
      responses:
        '202':
          description: Accepted for background processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads_lists/folders:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: listLeadListFolders
      summary: List lead list folders
      tags:
      - Lists
      responses:
        '200':
          description: List lead list folders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: createLeadListFolder
      summary: Create a lead list folder
      description: When `color` is omitted the folder gets a random color from the palette's vivid swatches.
      tags:
      - Lists
      responses:
        '201':
          description: Create a lead list folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads_lists/folders/{id}:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getLeadListFolder
      summary: Get a lead list folder
      tags:
      - Lists
      responses:
        '200':
          description: Get a lead list folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateLeadListFolder
      summary: Update a lead list folder
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    put:
      operationId: replaceLeadListFolder
      summary: Replace a lead list folder
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: deleteLeadListFolder
      summary: Delete a lead list folder
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads_lists/{id}/favorite:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: favoriteLeadList
      summary: Favorite a lead list
      tags:
      - Lists
      responses:
        '201':
          description: Favorite a lead list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: unfavoriteLeadList
      summary: Unfavorite a lead list
      tags:
      - Lists
      responses:
        '200':
          description: Unfavorite a lead list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads_lists/{id}/merge:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: mergeLeadLists
      summary: Merge lead lists
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads-lists:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: listLeadListsHyphen
      summary: List lead lists (hyphen alias)
      tags:
      - Lists
      responses:
        '200':
          description: List lead lists (hyphen alias).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: createLeadListHyphen
      summary: Create a lead list (hyphen alias)
      tags:
      - Lists
      responses:
        '201':
          description: Create a lead list (hyphen alias).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads-lists/{id}:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getLeadListHyphen
      summary: Get a lead list (hyphen alias)
      description: 'When the person behind a lead has asked Hunter to delete their address, with a claim or a California DROP request, the lead is returned without it: `email`, `confidence_score`, `verification.date` and `verification.status` are null (HUN-23599).'
      tags:
      - Lists
      responses:
        '200':
          description: Get a lead list (hyphen alias).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateLeadListHyphen
      summary: Update a lead list (hyphen alias)
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    put:
      operationId: replaceLeadListHyphen
      summary: Replace a lead list (hyphen alias)
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: deleteLeadListHyphen
      summary: Delete a lead list (hyphen alias)
      tags:
      - Lists
      responses:
        '202':
          description: Accepted for background processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads-lists/folders:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: listLeadListFoldersHyphen
      summary: List lead list folders (hyphen alias)
      tags:
      - Lists
      responses:
        '200':
          description: List lead list folders (hyphen alias).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: createLeadListFolderHyphen
      summary: Create a lead list folder (hyphen alias)
      description: When `color` is omitted the folder gets a random color from the palette's vivid swatches.
      tags:
      - Lists
      responses:
        '201':
          description: Create a lead list folder (hyphen alias).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads-lists/folders/{id}:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getLeadListFolderHyphen
      summary: Get a lead list folder (hyphen alias)
      tags:
      - Lists
      responses:
        '200':
          description: Get a lead list folder (hyphen alias).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateLeadListFolderHyphen
      summary: Update a lead list folder (hyphen alias)
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    put:
      operationId: replaceLeadListFolderHyphen
      summary: Replace a lead list folder (hyphen alias)
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: deleteLeadListFolderHyphen
      summary: Delete a lead list folder (hyphen alias)
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads-lists/{id}/favorite:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: favoriteLeadListHyphen
      summary: Favorite a lead list (hyphen alias)
      tags:
      - Lists
      responses:
        '201':
          description: Favorite a lead list (hyphen alias).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: unfavoriteLeadListHyphen
      summary: Unfavorite a lead list (hyphen alias)
      tags:
      - Lists
      responses:
        '200':
          description: Unfavorite a lead list (hyphen alias).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /leads-lists/{id}/merge:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: mergeLeadListsHyphen
      summary: Merge lead lists (hyphen alias)
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /company-lists:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: listCompanyLists
      summary: List company lists
      tags:
      - Lists
      responses:
        '200':
          description: List company lists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: createCompanyList
      summary: Create a company list
      tags:
      - Lists
      responses:
        '201':
          description: Create a company list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /company-lists/{id}:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getCompanyList
      summary: Get a company list
      tags:
      - Lists
      responses:
        '200':
          description: Get a company list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateCompanyList
      summary: Update a company list
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    put:
      operationId: replaceCompanyList
      summary: Replace a company list
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: deleteCompanyList
      summary: Delete a company list
      tags:
      - Lists
      responses:
        '202':
          description: Accepted for background processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /company-lists/folders:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: listCompanyListFolders
      summary: List company list folders
      tags:
      - Lists
      responses:
        '200':
          description: List company list folders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: createCompanyListFolder
      summary: Create a company list folder
      description: When `color` is omitted the folder gets a random color from the palette's vivid swatches.
      tags:
      - Lists
      responses:
        '201':
          description: Create a company list folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /company-lists/folders/{id}:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getCompanyListFolder
      summary: Get a company list folder
      tags:
      - Lists
      responses:
        '200':
          description: Get a company list folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateCompanyListFolder
      summary: Update a company list folder
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    put:
      operationId: replaceCompanyListFolder
      summary: Replace a company list folder
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: deleteCompanyListFolder
      summary: Delete a company list folder
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /company-lists/{id}/favorite:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: favoriteCompanyList
      summary: Favorite a company list
      tags:
      - Lists
      responses:
        '201':
          description: Favorite a company list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: unfavoriteCompanyList
      summary: Unfavorite a company list
      tags:
      - Lists
      responses:
        '200':
          description: Unfavorite a company list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /company-lists/{id}/companies:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: addCompanyListCompany
      summary: Add a company to a company list
      tags:
      - Lists
      responses:
        '201':
          description: Add a company to a company list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /company-lists/{id}/companies/{company_id}:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    - name: company_id
      in: path
      required: true
      schema:
        type: string
    delete:
      operationId: removeCompanyListCompany
      summary: Remove a company from a company list
      tags:
      - Lists
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /lookalikes:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: company_list_id
      in: query
      description: Identifier of the static company list to find lookalikes for. Provide exactly one of company_list_id or domain.
      schema:
        type: integer
    - name: domain
      in: query
      description: Domain name of one company to find lookalikes for (e.g. stripe.com). A URL is accepted and cleaned to its domain. Provide exactly one of company_list_id or domain. An unknown domain returns an empty list.
      schema:
        type: string
        example: stripe.com
    - name: country
      in: query
      description: 'Bias the ranking toward a given country (ISO 3166-1 alpha-2 code, e.g. us). This is a ranking signal, not a hard filter: companies from other countries may still appear.'
      schema:
        type: string
    - name: size
      in: query
      description: Only return companies in the given size range (e.g. 51-200). To send several ranges, use Rails-style bracket encoding (size[]=51-200&size[]=11-50); a repeated plain key (size=51-200&size=11-50) keeps only the last value. Companies without a known size are excluded.
      schema:
        anyOf:
        - type: string
        - type: array
          items:
            type: string
    - name: industry
      in: query
      description: Only return companies in the given industry (matched by name, case-insensitive). To send several industries, use Rails-style bracket encoding (industry[]=SaaS&industry[]=Fintech); a repeated plain key keeps only the last value. Companies without a known industry are excluded.
      schema:
        anyOf:
        - type: string
        - type: array
          items:
            type: string
    - name: limit
      in: query
      description: Maximum number of lookalikes to return. Because the size and industry filters are applied after ranking, a narrow filter can return fewer.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    get:
      operationId: listLookalikes
      summary: Find lookalike companies from a company list or a domain
      description: 'Finds companies that look like the ones in one of your company lists, or like one company given by its domain. The seed companies are excluded, and we return the most similar companies ranked by a similarity score. This endpoint is not paginated: it returns a single ranked page of the top limit results, so the offset parameter is not supported and returns 400 if supplied. This call is free.'
      tags:
      - Lists
      responses:
        '200':
          description: Lookalike companies ranked by similarity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lookalikes_response'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
components:
  responses:
    Error:
      description: The request could not be completed. A 429 with the error id `restricted_account` means the account is blocked, suspended or delinquent; further requests with the same API key are then rejected before reaching the API for up to 10 minutes, while the account and usage endpoints stay available.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
  schemas:
    generic_resource_response:
      type: object
      additionalProperties: true
      description: Generic envelope for V2 resource operations whose detailed schema is not yet in the contract.
    error_response:
      oneOf:
      - $ref: '#/components/schemas/standard_error_response'
      - $ref: '#/components/schemas/legacy_error_response'
    nullable_string:
      type:
      - string
      - 'null'
    standard_error_response:
      type: object
      additionalProperties: false
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - id
            - code
            - details
            properties:
              id:
                type: string
              code:
                type: integer
              details:
                type: string
    lookalikes_response:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - domain
            - company_name
            - country
            - industry
            - size
            - similarity_score
            properties:
              domain:
                type: string
                example: example.com
              company_name:
                $ref: '#/components/schemas/nullable_string'
              country:
                $ref: '#/components/schemas/nullable_string'
              industry:
                $ref: '#/components/schemas/nullable_string'
              size:
                allOf:
                - $ref: '#/components/schemas/nullable_string'
                description: Company size range (e.g. "51-200"). Null when unknown.
              similarity_score:
                type: number
                description: Similarity score ranking this company against the seed.
                example: 85.2
        meta:
          type: object
          additionalProperties: false
          required:
          - results
          - limit
          - params
          properties:
            results:
              type: integer
              description: Number of lookalike companies returned after filtering.
            limit:
              type: integer
              description: Maximum number of lookalikes requested.
            params:
              type: object
              additionalProperties: false
              required:
              - country
              - industry
              - size
              description: Echo of the applied parameters. Multi-value filters are returned as arrays.
              properties:
                company_list_id:
                  type: integer
                  description: Present when the seed is a company list.
                domain:
                  type: string
                  description: The cleaned seed domain. Present when the seed is a domain.
                country:
                  $ref: '#/components/schemas/nullable_string'
                industry:
                  type: array
                  items:
                    type: string
                size:
                  type: array
                  items:
                    type: string
    legacy_error_response:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error: {}
  parameters:
    ApiKey:
      name: api_key
      in: query
      description: Hunter API key. Prefer the X-API-KEY header outside browser links.
      schema:
        type: string
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
    bearerAuth:
      type: http
      scheme: bearer
x-provenance:
  method: harvested
  publisher: Hunter
  source: https://hunter.io/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)