Hunter Finder API

openapi: 3.2.0
info:
  title: Hunter Finder 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: Finder
paths:
  /domain-search:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: domain
      in: query
      description: Domain name to search.
      schema:
        type: string
    - name: company
      in: query
      description: Company name to search when the domain is unknown.
      schema:
        type: string
    - name: type
      in: query
      schema:
        type: string
        enum:
        - personal
        - generic
    - $ref: '#/components/parameters/Limit'
    - $ref: '#/components/parameters/Offset'
    - name: department
      in: query
      description: 'Comma-separated department values from Hunter''s live position taxonomy (not a frozen enum). `~` matches people with no department. Unknown values are ignored; a list with no remaining valid values returns 400 (`invalid_department`).

        '
      schema:
        type: string
        example: sales,marketing
    - name: source_type
      in: query
      schema:
        type: string
        enum:
        - found
        - generated
    - name: job_titles
      in: query
      schema:
        type: string
    - name: seniority
      in: query
      description: 'Comma-separated seniority values from Hunter''s live position taxonomy (not a frozen enum). Unknown values are ignored; a list with no remaining valid values returns 400 (`invalid_seniority`).

        '
      schema:
        type: string
        example: senior,executive
    - name: decision_maker
      in: query
      schema:
        $ref: '#/components/schemas/strict_boolean_filter'
    - name: required_field
      in: query
      schema:
        type: string
    - name: verification_status
      in: query
      schema:
        type: string
    - name: aggregations
      in: query
      schema:
        type: boolean
    - name: saved_leads
      in: query
      schema:
        type: boolean
    get:
      operationId: searchDomain
      summary: Find email addresses by domain
      tags:
      - Finder
      responses:
        '200':
          description: Email addresses and public sources for the domain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain_search_response'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: searchDomainWithPost
      summary: Find email addresses by domain using request-body parameters
      description: Use POST for nested location filters. The body can be JSON or URL-encoded form data.
      tags:
      - Finder
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/domain_search_request'
          application/json:
            schema:
              $ref: '#/components/schemas/domain_search_request'
      responses:
        '200':
          description: Email addresses and public sources for the domain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain_search_response'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /email-finder:
    get:
      operationId: findEmail
      summary: Find a professional email address
      description: Supply a LinkedIn handle, or supply a domain/company plus either a full name or first and last name. A found email address is also saved automatically to your leads. This is enabled by default and can be disabled for your account. The saved lead leaves out a phone number that is on a data broker deletion list, such as California's DROP.
      tags:
      - Finder
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: domain
        in: query
        description: Domain name of the company. A URL or a leading "@" is accepted and reduced to the domain name, so "https://www.example.com/about" and "@example.com" search example.com.
        schema:
          type: string
      - name: company
        in: query
        schema:
          type: string
      - name: first_name
        in: query
        schema:
          type: string
      - name: last_name
        in: query
        schema:
          type: string
      - name: full_name
        in: query
        schema:
          type: string
      - name: linkedin_handle
        in: query
        schema:
          type: string
      - name: max_duration
        in: query
        schema:
          type: integer
          minimum: 3
          maximum: 20
          default: 10
      responses:
        '200':
          description: The best matching email and supporting sources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email_finder_response'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          description: No available profile matches the supplied identifier. Email ID and LinkedIn handle lookups also return this response when the matching email is claimed for removal, even if its profile is still stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '429':
          $ref: '#/components/responses/Error'
        default:
          description: An error occurred. If removal-claim checks are unavailable, the request fails without returning an unchecked email address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
  /email-count:
    get:
      operationId: countDomainEmails
      summary: Count email addresses for a domain
      description: Return aggregate counts without revealing individual email addresses. This operation is free.
      tags:
      - Finder
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: domain
        in: query
        description: Domain name to count.
        schema:
          type: string
      - name: company
        in: query
        description: Company name to count when the domain is unknown.
        schema:
          type: string
      - name: type
        in: query
        schema:
          type: string
          enum:
          - personal
          - generic
      - name: include_job_titles
        in: query
        description: Include job-title counts when set to any non-empty value. An empty value or omission disables it.
        schema:
          type: string
          example: '1'
      responses:
        '200':
          description: Aggregate email counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email_count_response'
        '400':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /domain-count:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: countDomains
      summary: Count domains matching discovery filters
      tags:
      - Finder
      security: []
      responses:
        '200':
          description: Count domains matching discovery filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /domain-finder:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: company
      in: query
      description: Company name to resolve to a domain.
      schema:
        type: string
    - name: limit
      in: query
      description: Maximum suggestions to return.
      schema:
        type: integer
    - name: perfect_match
      in: query
      description: Only return an exact company-name match.
      schema:
        type: boolean
    get:
      operationId: findDomain
      summary: Find the domain for a company
      tags:
      - Finder
      responses:
        '200':
          description: Find the domain for a company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: findDomainWithPost
      summary: Find the domain for a company via POST
      tags:
      - Finder
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/domain_finder_request'
          application/json:
            schema:
              $ref: '#/components/schemas/domain_finder_request'
      responses:
        '200':
          description: Find the domain for a company via POST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /multi-domain-search/reveal:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    post:
      operationId: revealMultiDomainSearch
      summary: Reveal emails from a multi-domain search
      tags:
      - Finder
      responses:
        '200':
          description: Reveal emails from a multi-domain search. Emails claimed for removal have a not_found outcome and are omitted from the revealed data, including emails previously revealed to the team. No credits are charged for these emails.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          description: An error occurred. If removal-claim checks are unavailable, the request fails without returning unchecked email addresses or charging credits for them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
  /domains-suggestion:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: query
      in: query
      description: Company name to suggest domains for.
      schema:
        type: string
    - name: limit
      in: query
      description: Maximum suggestions to return.
      schema:
        type: integer
    get:
      operationId: suggestDomains
      summary: Suggest domains for a company name
      tags:
      - Finder
      responses:
        '200':
          description: Suggest domains for a company name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /email-finder/found:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: domain
      in: query
      schema:
        type: string
    - name: company
      in: query
      schema:
        type: string
    - name: first_name
      in: query
      schema:
        type: string
    - name: last_name
      in: query
      schema:
        type: string
    - name: full_name
      in: query
      schema:
        type: string
    - name: linkedin_handle
      in: query
      schema:
        type: string
    - name: max_duration
      in: query
      schema:
        type: integer
        minimum: 3
        maximum: 20
        default: 10
    get:
      operationId: findEmailFound
      summary: Get a previously found email address
      description: Found-only variant of email finder. Supply a LinkedIn handle, or supply a domain/company plus either a full name or first and last name.
      tags:
      - Finder
      responses:
        '200':
          description: The best matching found email and supporting sources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email_finder_response'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: findEmailFoundWithPost
      summary: Get a previously found email address via POST
      description: Found-only variant of email finder using request-body parameters.
      tags:
      - Finder
      responses:
        '200':
          description: The best matching found email and supporting sources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email_finder_response'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
components:
  schemas:
    domain_search_request:
      type: object
      additionalProperties: false
      properties:
        api_key:
          type: string
        domain:
          type: string
        company:
          type: string
        type:
          type: string
          enum:
          - personal
          - generic
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        offset:
          type: integer
          minimum: 0
          default: 0
        department:
          type: string
          description: 'Comma-separated department values from Hunter''s live position taxonomy (not a frozen enum). `~` matches people with no department. Unknown values are ignored; a list with no remaining valid values returns 400 (`invalid_department`).

            '
          example: sales,marketing
        source_type:
          type: string
          enum:
          - found
          - generated
        job_titles:
          type: string
        seniority:
          type: string
          description: 'Comma-separated seniority values from Hunter''s live position taxonomy (not a frozen enum). Unknown values are ignored; a list with no remaining valid values returns 400 (`invalid_seniority`).

            '
          example: senior,executive
        decision_maker:
          $ref: '#/components/schemas/strict_boolean_filter'
        required_field:
          type: string
        verification_status:
          type: string
        aggregations:
          type: boolean
        saved_leads:
          type: boolean
        location:
          $ref: '#/components/schemas/location_filter'
    generic_resource_response:
      type: object
      additionalProperties: true
      description: Generic envelope for V2 resource operations whose detailed schema is not yet in the contract.
    nullable_string:
      type:
      - string
      - 'null'
    source:
      type: object
      additionalProperties: false
      required:
      - domain
      - uri
      - extracted_on
      - last_seen_on
      - still_on_page
      properties:
        id:
          type: integer
        domain:
          type: string
        uri:
          type: string
          format: uri
        extracted_on:
          type: string
          format: date
        last_seen_on:
          type: string
          format: date
        still_on_page:
          type: boolean
    location_filter:
      type: object
      additionalProperties: false
      properties:
        include:
          $ref: '#/components/schemas/location_filter_collection'
        exclude:
          $ref: '#/components/schemas/location_filter_collection'
    legacy_error_response:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error: {}
    nullable_integer:
      type:
      - integer
      - 'null'
    domain_search_response:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - domain
          - disposable
          - webmail
          - accept_all
          - pattern
          - organization
          - linked_domains
          - emails
          properties:
            domain:
              $ref: '#/components/schemas/nullable_string'
            disposable:
              type: boolean
            webmail:
              type: boolean
            accept_all:
              type: boolean
            pattern:
              $ref: '#/components/schemas/nullable_string'
            organization:
              $ref: '#/components/schemas/nullable_string'
            linked_domains:
              type: array
              items:
                type: string
            emails:
              type: array
              items:
                $ref: '#/components/schemas/domain_search_email'
        meta:
          type: object
          additionalProperties: false
          required:
          - results
          - results_approximate
          - limit
          - offset
          - params
          properties:
            results:
              type: integer
            results_approximate:
              type: boolean
            limit:
              type: integer
            offset:
              type: integer
            aggregations:
              type: object
              additionalProperties: false
              required:
              - departments
              - decision_makers
              - personal
              - generic
              properties:
                departments:
                  type: object
                  description: Counts keyed by the department values stored by Hunter's classifier.
                  additionalProperties:
                    type: integer
                decision_makers:
                  type: integer
                personal:
                  type: integer
                generic:
                  type: integer
            params:
              type: object
              additionalProperties: false
              required:
              - domain
              - company
              - type
              - seniority
              - department
              - decision_maker
              properties:
                domain:
                  $ref: '#/components/schemas/nullable_string'
                company:
                  $ref: '#/components/schemas/nullable_string'
                type:
                  $ref: '#/components/schemas/nullable_string'
                seniority:
                  $ref: '#/components/schemas/nullable_string'
                department:
                  $ref: '#/components/schemas/nullable_string'
                decision_maker:
                  oneOf:
                  - type: boolean
                  - $ref: '#/components/schemas/nullable_string'
    error_response:
      oneOf:
      - $ref: '#/components/schemas/standard_error_response'
      - $ref: '#/components/schemas/legacy_error_response'
    location_filter_collection:
      oneOf:
      - type: array
        items:
          $ref: '#/components/schemas/location_filter_item'
      - type: object
        additionalProperties:
          $ref: '#/components/schemas/location_filter_item'
    location_filter_item:
      type: object
      additionalProperties: false
      properties:
        continent:
          type: string
        business_region:
          type: string
        country:
          type: string
          minLength: 2
          maxLength: 2
        state:
          type: string
        city:
          type: string
    strict_boolean_filter:
      description: A boolean filter. Query-string clients may use the documented case-insensitive aliases.
      anyOf:
      - type: boolean
      - type: integer
        enum:
        - 0
        - 1
      - type: string
        pattern: ^\s*(?:[Tt][Rr][Uu][Ee]|[Tt]|1|[Oo][Nn]|[Yy][Ee][Ss]|[Yy]|[Ff][Aa][Ll][Ss][Ee]|[Ff]|0|[Oo][Ff][Ff]|[Nn][Oo]|[Nn])\s*$
    email_count_response:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - total
          - personal_emails
          - generic_emails
          - department
          - seniority
          properties:
            total:
              type: integer
            personal_emails:
              type: integer
            generic_emails:
              type: integer
            department:
              type: object
              description: Counts keyed by the department values stored by Hunter's classifier. Only email addresses with a known department are counted, so the sum can be less than total.
              additionalProperties:
                type: integer
            seniority:
              type: object
              description: Counts keyed by seniority. Only email addresses with a known seniority are counted, so the sum can be less than total.
              additionalProperties:
                type: integer
            job_titles:
              type: object
              additionalProperties:
                type: integer
        meta:
          type: object
          additionalProperties: false
          required:
          - params
          properties:
            params:
              type: object
              additionalProperties: false
              required:
              - domain
              - company
              - type
              properties:
                domain:
                  $ref: '#/components/schemas/nullable_string'
                company:
                  $ref: '#/components/schemas/nullable_string'
                type:
                  $ref: '#/components/schemas/nullable_string'
    domain_search_email:
      type: object
      additionalProperties: false
      required:
      - value
      - type
      - source_type
      - confidence
      - sources
      - first_name
      - last_name
      - position
      - position_raw
      - seniority
      - department
      - decision_maker
      - linkedin
      - twitter
      - phone_number
      - verification
      properties:
        id:
          type: integer
        value:
          type: string
          format: email
        type:
          type: string
          enum:
          - personal
          - generic
        source_type:
          type: string
          enum:
          - found
          - generated
        confidence:
          type: integer
        sources:
          type: array
          items:
            $ref: '#/components/schemas/source'
        first_name:
          $ref: '#/components/schemas/nullable_string'
        last_name:
          $ref: '#/components/schemas/nullable_string'
        position:
          $ref: '#/components/schemas/nullable_string'
        position_raw:
          $ref: '#/components/schemas/nullable_string'
        seniority:
          $ref: '#/components/schemas/nullable_string'
        department:
          type:
          - string
          - 'null'
          description: Department value stored by Hunter's classifier, such as `finance & accounting`.
        decision_maker:
          type: boolean
        linkedin:
          $ref: '#/components/schemas/nullable_string'
        twitter:
          $ref: '#/components/schemas/nullable_string'
        phone_number:
          type:
          - string
          - 'null'
          description: Null when Hunter holds no phone number for the person, or when the number is on the California DROP list.
        verification:
          $ref: '#/components/schemas/verification_summary'
    email_finder_response:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - first_name
          - last_name
          - email
          - score
          - domain
          - accept_all
          - position
          - twitter
          - linkedin_url
          - phone_number
          - company
          - source_type
          - sources
          - verification
          properties:
            first_name:
              $ref: '#/components/schemas/nullable_string'
            last_name:
              $ref: '#/components/schemas/nullable_string'
            email:
              $ref: '#/components/schemas/nullable_string'
            score:
              $ref: '#/components/schemas/nullable_integer'
            domain:
              $ref: '#/components/schemas/nullable_string'
            accept_all:
              $ref: '#/components/schemas/nullable_boolean'
            position:
              $ref: '#/components/schemas/nullable_string'
            twitter:
              $ref: '#/components/schemas/nullable_string'
            linkedin_url:
              $ref: '#/components/schemas/nullable_string'
            phone_number:
              type:
              - string
              - 'null'
              description: Null when Hunter holds no phone number for the person, or when the number is on the California DROP list.
            company:
              $ref: '#/components/schemas/nullable_string'
            source_type:
              $ref: '#/components/schemas/nullable_string'
            sources:
              type: array
              items:
                $ref: '#/components/schemas/source'
            verification:
              $ref: '#/components/schemas/verification_summary'
        meta:
          type: object
          additionalProperties: false
          required:
          - params
          properties:
            params:
              type: object
              additionalProperties: false
              required:
              - first_name
              - last_name
              - full_name
              - domain
              - company
              - linkedin_handle
              - max_duration
              properties:
                first_name:
                  $ref: '#/components/schemas/nullable_string'
                last_name:
                  $ref: '#/components/schemas/nullable_string'
                full_name:
                  $ref: '#/components/schemas/nullable_string'
                domain:
                  $ref: '#/components/schemas/nullable_string'
                company:
                  $ref: '#/components/schemas/nullable_string'
                linkedin_handle:
                  $ref: '#/components/schemas/nullable_string'
                max_duration:
                  $ref: '#/components/schemas/nullable_string'
    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
    domain_finder_request:
      type: object
      additionalProperties: true
      required:
      - company
      properties:
        company:
          type: string
          description: Company name to resolve to a domain.
        limit:
          type: integer
          description: Maximum suggestions to return.
        perfect_match:
          type: boolean
          description: Only return an exact company-name match.
    verification_summary:
      type: object
      additionalProperties: false
      required:
      - date
      - status
      properties:
        id:
          $ref: '#/components/schemas/nullable_integer'
        date:
          $ref: '#/components/schemas/nullable_string'
        status:
          $ref: '#/components/schemas/nullable_string'
    nullable_boolean:
      type:
      - boolean
      - 'null'
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    ApiKey:
      name: api_key
      in: query
      description: Hunter API key. Prefer the X-API-KEY header outside browser links.
      schema:
        type: string
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
  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'
  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)