openapi: 3.1.0
info:
  title: Hunter Discover API
  description: >
    Find companies that match a target customer profile using natural-language
    queries or structured filters across industry, headcount, location, technology,
    funding, and keywords. The Discover API powers Hunter's prospecting workflows
    and feeds directly into Domain Search and Email Finder.
  version: v2
  contact:
    name: Hunter Support
    url: https://hunter.io/contact
servers:
  - url: https://api.hunter.io/v2
    description: Production
security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []
  - BearerAuth: []
tags:
  - name: Discover
    description: Company discovery and prospecting.
paths:
  /discover:
    post:
      summary: Hunter Discover Companies
      description: >
        Search Hunter's company database via natural-language `query` or structured
        filters (industry, headcount, location, technology, funding, keywords).
        Returns matching companies with email-count summaries so you can prioritize
        targets before running Domain Search.
      operationId: discoverCompanies
      tags:
        - Discover
      parameters:
        - $ref: '#/components/parameters/ApiKeyQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoverRequest'
      responses:
        '200':
          description: Companies matching the criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverResponse'
        '400':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
components:
  securitySchemes:
    ApiKeyQuery: { type: apiKey, in: query, name: api_key }
    ApiKeyHeader: { type: apiKey, in: header, name: X-API-KEY }
    BearerAuth: { type: http, scheme: bearer }
  parameters:
    ApiKeyQuery:
      name: api_key
      in: query
      required: true
      description: Your Hunter API key.
      schema: { type: string }
  schemas:
    DiscoverRequest:
      type: object
      properties:
        query:
          type: string
          description: Natural-language description of the target company set.
        organization:
          type: object
          properties:
            domain: { type: array, items: { type: string } }
            name: { type: array, items: { type: string } }
        similar_to:
          type: string
          description: Premium-only. Domain to find lookalike companies from.
        headquarters_location:
          type: object
          properties:
            include:
              type: object
              properties:
                continent: { type: array, items: { type: string } }
                country: { type: array, items: { type: string } }
                state: { type: array, items: { type: string } }
                city: { type: array, items: { type: string } }
            exclude:
              type: object
              properties:
                country: { type: array, items: { type: string } }
        industry:
          type: object
          properties:
            include: { type: array, items: { type: string } }
            exclude: { type: array, items: { type: string } }
        headcount:
          type: array
          items: { type: string, enum: ['1-10','11-50','51-200','201-500','501-1000','1001-5000','5001-10000','10001+'] }
        company_type:
          type: array
          items: { type: string, enum: [educational, government, nonprofit, partnership, privately_held, public_company, self_employed, self_owned] }
        year_founded:
          type: object
          properties:
            min: { type: integer }
            max: { type: integer }
        keywords:
          type: object
          properties:
            include: { type: array, items: { type: string } }
            exclude: { type: array, items: { type: string } }
            match: { type: string, enum: [any, all] }
        technology:
          type: object
          properties:
            include: { type: array, items: { type: string } }
            exclude: { type: array, items: { type: string } }
        funding:
          type: object
          properties:
            stage: { type: array, items: { type: string } }
            min_amount: { type: integer }
            max_amount: { type: integer }
        limit: { type: integer, default: 100, maximum: 100 }
        offset: { type: integer, default: 0, maximum: 10000 }
    DiscoverResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              domain: { type: string }
              organization: { type: string }
              industry: { type: string }
              headcount: { type: string }
              country: { type: string }
              emails_count:
                type: object
                properties:
                  total: { type: integer }
                  personal: { type: integer }
                  generic: { type: integer }
        meta:
          type: object
          properties:
            results: { type: integer }
            filters:
              type: object
              additionalProperties: true
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              id: { type: string }
              code: { type: integer }
              details: { type: string }
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }