Hunter Discover API

openapi: 3.2.0
info:
  title: Hunter Discover 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: Discover
paths:
  /discover:
    post:
      operationId: discoverCompanies
      summary: Discover companies
      description: Find companies matching a structured filter set. This operation is free.
      tags:
      - Discover
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/discover_request'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/discover_request'
      responses:
        '200':
          description: Matching companies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/discover_response'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /discover/people:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: discoverPeople
      summary: Discover people matching filters
      tags:
      - Discover
      responses:
        '200':
          description: Discover people matching filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: discoverPeopleWithPost
      summary: Discover people using request-body filters
      tags:
      - Discover
      responses:
        '200':
          description: Discover people using request-body filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
components:
  schemas:
    generic_resource_response:
      type: object
      additionalProperties: true
      description: Generic envelope for V2 resource operations whose detailed schema is not yet in the contract.
    discover_similar_to_filter:
      type: object
      additionalProperties: false
      properties:
        domain:
          type: string
        organization:
          type: string
    nullable_string:
      type:
      - string
      - 'null'
    discover_company:
      type: object
      additionalProperties: false
      required:
      - domain
      - organization
      - emails_count
      properties:
        domain:
          type: string
        organization:
          $ref: '#/components/schemas/nullable_string'
        emails_count:
          $ref: '#/components/schemas/discover_email_counts'
        description:
          $ref: '#/components/schemas/nullable_string'
        industry:
          $ref: '#/components/schemas/nullable_string'
        technologies:
          type: array
          items:
            type: string
        country:
          $ref: '#/components/schemas/nullable_string'
        state:
          $ref: '#/components/schemas/nullable_string'
        city:
          $ref: '#/components/schemas/nullable_string'
        headcount:
          $ref: '#/components/schemas/nullable_string'
        company_type:
          $ref: '#/components/schemas/nullable_string'
        year_founded:
          $ref: '#/components/schemas/nullable_integer'
        keywords:
          type:
          - array
          - 'null'
          items:
            type: string
        already_saved:
          type: boolean
        socials:
          type: object
          additionalProperties: false
          required:
          - twitter
          - facebook
          - instagram
          - youtube
          properties:
            twitter:
              $ref: '#/components/schemas/nullable_string'
            facebook:
              $ref: '#/components/schemas/nullable_string'
            instagram:
              $ref: '#/components/schemas/nullable_string'
            youtube:
              $ref: '#/components/schemas/nullable_string'
        technology_details:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - slug
            - name
            - category
            - category_label
            - website
            properties:
              slug:
                type: string
              name:
                $ref: '#/components/schemas/nullable_string'
              category:
                $ref: '#/components/schemas/nullable_string'
              category_label:
                $ref: '#/components/schemas/nullable_string'
              website:
                $ref: '#/components/schemas/nullable_string'
    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'
    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
    discover_year_founded_filter:
      type: object
      additionalProperties: false
      properties:
        include:
          type: array
          items:
            type: integer
            minimum: 1000
            maximum: 9999
        exclude:
          type: array
          items:
            type: integer
            minimum: 1000
            maximum: 9999
        from:
          type: integer
          minimum: 1000
          maximum: 9999
        to:
          type: integer
          minimum: 1000
          maximum: 9999
    discover_funding_filter:
      type: object
      additionalProperties: false
      properties:
        received:
          type: boolean
        series:
          type: array
          items:
            type: string
            enum:
            - pre_seed
            - seed
            - pre_series_a
            - series_a
            - pre_series_b
            - series_b
            - pre_series_c
            - series_c+
            - other
        amount:
          type: object
          additionalProperties: false
          required:
          - from
          - to
          properties:
            from:
              type: integer
              minimum: 0
            to:
              type: integer
              minimum: 0
        date:
          type: object
          description: Inclusive calendar-date range in YYYY-MM-DD format. Either bound may be omitted to leave that side of the range open. Applied dates, including those resolved from a natural-language query, are returned in meta.filters.funding.date and can be reused for pagination.
          additionalProperties: false
          properties:
            from:
              type: string
              format: date
            to:
              type: string
              format: date
    discover_response:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/discover_company'
        meta:
          type: object
          additionalProperties: false
          required:
          - results
          - limit
          - offset
          - params
          - filters
          properties:
            results:
              type: integer
            limit:
              type: integer
            offset:
              type: integer
            params:
              type: object
              additionalProperties: true
            filters:
              type: object
              description: Applied structured filters that can be reused for pagination. Funding date ranges resolved from natural-language queries are returned in funding.date as explicit, inclusive YYYY-MM-DD dates, preserving the date window when reused on a later day.
              additionalProperties: true
            permalink:
              $ref: '#/components/schemas/nullable_string'
    discover_email_counts:
      type: object
      additionalProperties: false
      required:
      - personal
      - generic
      - total
      properties:
        personal:
          $ref: '#/components/schemas/nullable_integer'
        generic:
          $ref: '#/components/schemas/nullable_integer'
        total:
          $ref: '#/components/schemas/nullable_integer'
    discover_request:
      type: object
      description: Use headquarters_location to include or exclude company locations. Country is required for state or city filters. States must be regions supported by Hunter's company location data. State codes are case-insensitive and surrounding whitespace is ignored. US states normalize to bare codes (CA); other regions normalize to country-prefixed ISO 3166-2 codes (FR-IDF). A bare code is accepted with its country (IDF with FR). The United Kingdom supports GB-ENG, GB-SCT, GB-WLS, and GB-NIR. Counties such as GB-WAR and GB-HRT return a validation error; use a city or choose a supported region. State is required for US cities and optional for other countries.
      additionalProperties: false
      properties:
        api_key:
          type: string
        query:
          type: string
          maxLength: 2000
        organization:
          $ref: '#/components/schemas/discover_organization_filter'
        similar_to:
          $ref: '#/components/schemas/discover_similar_to_filter'
        headquarters_location:
          $ref: '#/components/schemas/location_filter'
        industry:
          allOf:
          - $ref: '#/components/schemas/discover_string_collection_filter'
          description: Industry names to include or exclude.
        headcount:
          type: array
          items:
            type: string
            enum:
            - 1-10
            - 11-50
            - 51-200
            - 201-500
            - 501-1000
            - 1001-5000
            - 5001-10000
            - 10001+
        company_type:
          allOf:
          - $ref: '#/components/schemas/discover_string_collection_filter'
          description: Hunter company types to include or exclude.
        year_founded:
          $ref: '#/components/schemas/discover_year_founded_filter'
        keywords:
          $ref: '#/components/schemas/discover_match_filter'
        technology:
          allOf:
          - $ref: '#/components/schemas/discover_match_filter'
          description: Technology slugs to include or exclude.
        funding:
          $ref: '#/components/schemas/discover_funding_filter'
        job_openings:
          $ref: '#/components/schemas/discover_job_openings_filter'
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
          description: Number of companies to return. Every plan can request up to 100 companies.
        offset:
          type: integer
          minimum: 0
          maximum: 10000
          default: 0
          description: Number of companies to skip. Only plans with Discover paging can set an offset above 0.
    discover_organization_filter:
      type: object
      additionalProperties: false
      properties:
        domain:
          type: array
          items:
            type: string
        name:
          type: array
          items:
            type: string
    discover_string_collection_filter:
      type: object
      additionalProperties: false
      properties:
        include:
          type: array
          items:
            type: string
        exclude:
          type: array
          items:
            type: string
    discover_toggle_boolean:
      description: 'Boolean accepted by Discover job-opening toggles. Only true/false and 1/0 (case-insensitive strings). Aliases such as on/yes/y/off/no are rejected with 400, matching Api::Discover::Validations#boolean_literal?.

        '
      anyOf:
      - type: boolean
      - type: integer
        enum:
        - 0
        - 1
      - type: string
        pattern: ^(?:[Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee]|1|0)$
    discover_job_openings_filter:
      type: object
      additionalProperties: false
      description: 'Filter companies by LinkedIn job openings. Department values come from the jobs-index vocabulary (not a frozen enum). Unknown departments return 400.

        '
      properties:
        hiring:
          allOf:
          - $ref: '#/components/schemas/discover_toggle_boolean'
          description: When true, only companies currently hiring.
        include_closed_roles:
          allOf:
          - $ref: '#/components/schemas/discover_toggle_boolean'
          description: When true, include closed roles in the openings match.
        department:
          type: array
          maxItems: 100
          items:
            type: string
        job_title:
          type: object
          additionalProperties: false
          properties:
            include:
              type: array
              maxItems: 100
              items:
                type: string
            exclude:
              type: array
              maxItems: 100
              items:
                type: string
        posted_date:
          type: string
          enum:
          - last7d
          - last30d
          - last90d
        open_roles:
          type: object
          additionalProperties: false
          properties:
            from:
              type: integer
              minimum: 1
            to:
              type: integer
              minimum: 1
    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
    discover_match_filter:
      type: object
      additionalProperties: false
      properties:
        match:
          type: string
          enum:
          - all
          - any
          default: all
        include:
          type: array
          items:
            type: string
        exclude:
          type: array
          items:
            type: string
  parameters:
    ApiKey:
      name: api_key
      in: query
      description: Hunter API key. Prefer the X-API-KEY header outside browser links.
      schema:
        type: string
  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)