Hunter Discover API

openapi: 3.1.0
info:
  title: Hunter API
  description: >-
    Hunter is an email finding and verification service that helps find
    professional email addresses associated with a domain and verify email
    deliverability. The API provides domain search, email finder, email
    verifier, email count, account information, leads management, leads
    lists, campaigns, discover, enrichment, and logo retrieval capabilities.
  version: 2.0.0
  termsOfService: https://hunter.io/terms
  contact:
    name: Hunter Support
    url: https://hunter.io/contact
    email: [email protected]
  license:
    name: Proprietary
    url: https://hunter.io/terms

servers:
- url: https://api.hunter.io/v2
  description: Hunter API v2 Production

security:
- apiKeyQuery: []
- apiKeyHeader: []
- bearerAuth: []

tags:
- name: Account
  description: Retrieve account information and usage statistics.
- name: Campaigns
  description: Manage email sequences and recipients.
- name: Combined Enrichment
  description: Merge person and company enrichment for a single email address.

- name: Company Enrichment
  description: Enrich company information linked to a domain name.
- name: Discover
  description: Find companies matching criteria using natural language or filters.
- name: Domain Search
  description: Search for email addresses associated with a domain.
- name: Email Count
  description: Count email addresses found for a domain.
- name: Email Enrichment
  description: Enrich personal information linked to an email or LinkedIn profile.
- name: Email Finder
  description: Find the most likely email address for a person at a company.
- name: Email Verifier
  description: Verify the deliverability of an email address.
- name: Leads
  description: Manage leads stored in Hunter.
- name: Leads Lists
  description: Manage leads list collections in Hunter.
paths:
  /domain-search:
    get:
      operationId: domainSearch
      summary: Hunter Domain Search
      description: >-
        Returns all the email addresses found using a given domain name,
        with sources. You must provide either a domain or a company name.
      tags:
      - Domain Search
      parameters:
      - name: domain
        in: query
        description: >-
          Domain name from which you want to find the email addresses.
          Required if company is not provided.
        schema:
          type: string
        example: stripe.com
      - name: company
        in: query
        description: >-
          Company name from which you want to find the email addresses.
          Required if domain is not provided.
        schema:
          type: string
        example: Stripe
      - name: limit
        in: query
        description: Maximum number of email addresses to return. Default is 10.
        schema:
          type: integer
          default: 10
      - name: offset
        in: query
        description: Number of email addresses to skip for pagination. Default is 0.
        schema:
          type: integer
          default: 0
      - name: type
        in: query
        description: Filter by email address type.
        schema:
          type: string
          enum:
          - personal
          - generic
      - name: seniority
        in: query
        description: Filter by seniority level.
        schema:
          type: string
          enum:
          - junior
          - senior
          - executive
      - name: department
        in: query
        description: Filter by department.
        schema:
          type: string
      - name: verification_status
        in: query
        description: Filter by verification status.
        schema:
          type: string
          enum:
          - valid
          - accept_all
          - unknown
      responses:
        '200':
          description: Successful domain search response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DomainSearchResult'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /email-finder:
    get:
      operationId: emailFinder
      summary: Hunter Email Finder
      description: >-
        Finds the most likely email address from a domain name, a first
        name and a last name. You must provide a domain or company, and
        a name (first/last or full) or LinkedIn handle.
      tags:
      - Email Finder
      parameters:
      - name: domain
        in: query
        description: Domain name of the company. Required if company is not provided.
        schema:
          type: string
        example: stripe.com
      - name: company
        in: query
        description: Company name. Required if domain is not provided.
        schema:
          type: string
      - name: first_name
        in: query
        description: First name of the person. Required with last_name if full_name not provided.
        schema:
          type: string
        example: John
      - name: last_name
        in: query
        description: Last name of the person. Required with first_name if full_name not provided.
        schema:
          type: string
        example: Collison
      - name: full_name
        in: query
        description: Full name of the person. Required if first_name and last_name not provided.
        schema:
          type: string
      - name: linkedin_handle
        in: query
        description: LinkedIn profile handle for the person.
        schema:
          type: string
      - name: max_duration
        in: query
        description: Maximum duration for the request in seconds. Between 3 and 20, default is 10.
        schema:
          type: integer
          minimum: 3
          maximum: 20
          default: 10
      responses:
        '200':
          description: Successful email finder response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EmailFinderResult'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /email-verifier:
    get:
      operationId: emailVerifier
      summary: Hunter Email Verifier
      description: Verifies the deliverability of a given email address.
      tags:
      - Email Verifier
      parameters:
      - name: email
        in: query
        required: true
        description: The email address to verify.
        schema:
          type: string
          format: email
        example: [email protected]
      responses:
        '200':
          description: Successful email verification response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EmailVerifierResult'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '202':
          description: Verification in progress. Retry the request later.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EmailVerifierResult'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /email-count:
    get:
      operationId: emailCount
      summary: Hunter Email Count
      description: >-
        Returns the number of email addresses found for a given domain
        or company, broken down by type, department, and seniority.
      tags:
      - Email Count
      parameters:
      - name: domain
        in: query
        description: Domain name to count emails for. Required if company is not provided.
        schema:
          type: string
        example: stripe.com
      - name: company
        in: query
        description: Company name to count emails for. Required if domain is not provided.
        schema:
          type: string
      - name: type
        in: query
        description: Filter count by email type.
        schema:
          type: string
          enum:
          - personal
          - generic
      responses:
        '200':
          description: Successful email count response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EmailCountResult'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /account:
    get:
      operationId: getAccount
      summary: Hunter Account Information
      description: >-
        Returns information about the Hunter account associated with the
        API key, including usage statistics and plan details. This call
        is free and does not count toward usage limits.
      tags:
      - Account
      responses:
        '200':
          description: Successful account information response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AccountResult'
        '401':
          $ref: '#/components/responses/Unauthorized'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /leads:
    get:
      operationId: listLeads
      summary: Hunter List Leads
      description: Returns all the leads saved in your account.
      tags:
      - Leads
      parameters:
      - name: limit
        in: query
        description: Maximum number of leads to return. Default is 20, max is 100.
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: offset
        in: query
        description: Number of leads to skip for pagination.
        schema:
          type: integer
          default: 0
      - name: leads_list_id
        in: query
        description: Filter leads by list identifier.
        schema:
          type: integer
      - name: first_name
        in: query
        description: Filter by first name.
        schema:
          type: string
      - name: last_name
        in: query
        description: Filter by last name.
        schema:
          type: string
      - name: email
        in: query
        description: Filter by email address.
        schema:
          type: string
      - name: company
        in: query
        description: Filter by company name.
        schema:
          type: string
      - name: phone_number
        in: query
        description: Filter by phone number.
        schema:
          type: string
      - name: twitter
        in: query
        description: Filter by Twitter handle.
        schema:
          type: string
      responses:
        '200':
          description: Successful leads list response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      leads:
                        type: array
                        items:
                          $ref: '#/components/schemas/Lead'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createLead
      summary: Hunter Create Lead
      description: Creates a new lead in your Hunter account.
      tags:
      - Leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadInput'
      responses:
        '201':
          description: Lead created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Lead'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: upsertLead
      summary: Hunter Create or Update Lead
      description: >-
        Creates a new lead or updates an existing one if a lead with the
        same email address already exists in the specified list.
      tags:
      - Leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadInput'
      responses:
        '200':
          description: Lead updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Lead'
        '201':
          description: Lead created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Lead'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /leads/{id}:
    get:
      operationId: getLead
      summary: Hunter Get Lead
      description: Retrieves a single lead by its identifier.
      tags:
      - Leads
      parameters:
      - $ref: '#/components/parameters/LeadId'
      responses:
        '200':
          description: Successful lead retrieval.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Lead'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateLead
      summary: Hunter Update Lead
      description: Updates an existing lead by its identifier.
      tags:
      - Leads
      parameters:
      - $ref: '#/components/parameters/LeadId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadInput'
      responses:
        '200':
          description: Lead updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Lead'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteLead
      summary: Hunter Delete Lead
      description: Deletes a lead by its identifier.
      tags:
      - Leads
      parameters:
      - $ref: '#/components/parameters/LeadId'
      responses:
        '204':
          description: Lead deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /leads_lists:
    get:
      operationId: listLeadsLists
      summary: Hunter List Leads Lists
      description: Returns all the leads lists saved in your account.
      tags:
      - Leads Lists
      parameters:
      - name: limit
        in: query
        description: Maximum number of lists to return. Default is 20, max is 100.
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: offset
        in: query
        description: Number of lists to skip for pagination.
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Successful leads lists response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      leads_lists:
                        type: array
                        items:
                          $ref: '#/components/schemas/LeadsList'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createLeadsList
      summary: Hunter Create Leads List
      description: Creates a new leads list.
      tags:
      - Leads Lists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the leads list.
      responses:
        '201':
          description: Leads list created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LeadsList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /leads_lists/{id}:
    get:
      operationId: getLeadsList
      summary: Hunter Get Leads List
      description: Retrieves a single leads list by its identifier.
      tags:
      - Leads Lists
      parameters:
      - $ref: '#/components/parameters/LeadsListId'
      responses:
        '200':
          description: Successful leads list retrieval.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LeadsList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateLeadsList
      summary: Hunter Update Leads List
      description: Updates an existing leads list by its identifier.
      tags:
      - Leads Lists
      parameters:
      - $ref: '#/components/parameters/LeadsListId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The new name for the leads list.
      responses:
        '200':
          description: Leads list updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LeadsList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteLeadsList
      summary: Hunter Delete Leads List
      description: Deletes a leads list by its identifier.
      tags:
      - Leads Lists
      parameters:
      - $ref: '#/components/parameters/LeadsListId'
      responses:
        '204':
          description: Leads list deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /campaigns:
    get:
      operationId: listCampaigns
      summary: Hunter List Campaigns
      description: Returns all the email sequences (campaigns) in your account.
      tags:
      - Campaigns
      parameters:
      - name: limit
        in: query
        description: Maximum number of campaigns to return. Default is 20, max is 100.
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: offset
        in: query
        description: Number of campaigns to skip for pagination.
        schema:
          type: integer
          default: 0
      - name: started
        in: query
        description: Filter by whether the campaign has been started.
        schema:
          type: boolean
      - name: archived
        in: query
        description: Filter by whether the campaign has been archived.
        schema:
          type: boolean
      responses:
        '200':
          description: Successful campaigns list response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      campaigns:
                        type: array
                        items:
                          $ref: '#/components/schemas/Campaign'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /campaigns/{id}/recipients:
    get:
      operationId: listCampaignRecipients
      summary: Hunter List Campaign Recipients
      description: Returns the recipients for a given campaign.
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      - name: limit
        in: query
        description: Maximum number of recipients to return.
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: offset
        in: query
        description: Number of recipients to skip for pagination.
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Successful campaign recipients response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      recipients:
                        type: array
                        items:
                          $ref: '#/components/schemas/CampaignRecipient'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addCampaignRecipients
      summary: Hunter Add Campaign Recipients
      description: Adds recipients to a campaign using email addresses or lead identifiers.
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  oneOf:
                  - type: string
                  - type: array
                    items:
                      type: string
                  description: Email address or array of email addresses to add.
                lead_ids:
                  type: array
                  items:
                    type: integer
                  description: Array of lead identifiers to add as recipients.
      responses:
        '201':
          description: Recipients added successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: cancelCampaignRecipients
      summary: Hunter Cancel Campaign Recipients
      description: Cancels all scheduled emails for the specified recipients.
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  oneOf:
                  - type: string
                  - type: array
                    items:
                      type: string
                  description: Email address or array of email addresses to cancel.
      responses:
        '204':
          description: Scheduled emails cancelled successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /campaigns/{id}/start:
    post:
      operationId: startCampaign
      summary: Hunter Start Campaign
      description: Starts an email sequence for the campaign.
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      responses:
        '200':
          description: Campaign started successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /discover:
    post:
      operationId: discover
      summary: Hunter Discover Companies
      description: >-
        Returns companies matching a set of criteria using natural language
        queries or robust filters to find companies aligned with your ideal
        customer profile.
      tags:
      - Discover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoverRequest'
      responses:
        '200':
          description: Successful discover response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/DiscoverResult'
                      filters:
                        type: object
                        description: Applied filters for pagination context.
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /people/find:
    get:
      operationId: emailEnrichment
      summary: Hunter Email Enrichment
      description: >-
        Returns comprehensive personal information linked to an email
        address or LinkedIn profile. Provides enriched data points about
        the person including employment, social profiles, and location.
      tags:
      - Email Enrichment
      parameters:
      - name: email
        in: query
        description: Email address to enrich. Required if linkedin_handle is not provided.
        schema:
          type: string
          format: email
      - name: linkedin_handle
        in: query
        description: LinkedIn profile handle. Required if email is not provided.
        schema:
          type: string
      - name: clearbit_format
        in: query
        description: Format response to match the Clearbit schema.
        schema:
          type: boolean
      responses:
        '200':
          description: Successful email enrichment response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PersonEnrichment'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '451':
          $ref: '#/components/responses/UnavailableForLegalReasons'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies/find:
    get:
      operationId: companyEnrichment
      summary: Hunter Company Enrichment
      description: >-
        Returns detailed organizational data associated with a domain
        name, including company size, industry, location, and other
        firmographic information.
      tags:
      - Company Enrichment
      parameters:
      - name: domain
        in: query
        required: true
        description: Domain name of the company to enrich.
        schema:
          type: string
        example: stripe.com
      - name: clearbit_format
        in: query
        description: Format response to match the Clearbit schema.
        schema:
          type: boolean
      responses:
        '200':
          description: Successful company enrichment response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CompanyEnrichment'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /combined/find:
    get:
      operationId: combinedEnrichment
      summary: Hunter Combined Enrichment
      description: >-
        Merges person and company information for a single email address,
        returning enriched records combining both datasets.
      tags:
      - Combined Enrichment
      parameters:
      - name

# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hunter/refs/heads/main/openapi/hunter-api-openapi.yml