Hunter Multi-Domain Search API

openapi: 3.2.0
info:
  title: Hunter Multi-Domain Search 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: Multi-Domain Search
paths:
  /multi-domain-search:
    post:
      operationId: multiDomainSearch
      summary: Multi-domain search
      description: Search professional email addresses across many companies at once using a structured filter set. Returns masked rows — no email address or phone number; use the reveal endpoint to unmask. This masked survey operation is free. At least one filter is required. Filters may be sent in the request body (JSON or form-encoded) or as query-string parameters; the body is therefore optional.
      tags:
      - Multi-Domain Search
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/multi_domain_search_request'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/multi_domain_search_request'
      responses:
        '200':
          description: Masked rows matching the filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/multi_domain_search_response'
        '400':
          description: A filter is invalid. For an enum filter (`type`, `seniority`, `department`, `verification_status`, `required_field`), any unknown value rejects the whole request; `details` names the rejected values (at most 10, each cut to 50 characters) and lists the accepted ones.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $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:
    error_response:
      oneOf:
      - $ref: '#/components/schemas/standard_error_response'
      - $ref: '#/components/schemas/legacy_error_response'
    multi_domain_search_response:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/multi_domain_search_email'
        meta:
          type: object
          additionalProperties: false
          required:
          - results
          - next_search_after
          - params
          properties:
            results:
              type: integer
              description: Total number of matching rows.
            next_search_after:
              allOf:
              - $ref: '#/components/schemas/nullable_string'
              description: Cursor for the next page, or null on the last page. Pass it back as search_after.
            params:
              type: object
              additionalProperties: true
              description: Echo of the applied filters. Multi-value filters are returned as arrays.
            per_domain:
              type: array
              description: Per-domain result breakdown. Present only when per_domain was requested.
              items:
                type: object
                additionalProperties: false
                required:
                - domain
                - emails
                properties:
                  domain:
                    type: string
                  emails:
                    type: integer
    multi_domain_search_request:
      type: object
      additionalProperties: false
      description: Filter set for the multi-domain search. Multi-value filters accept a comma-separated string (the v2 convention). At least one filter is required.
      properties:
        api_key:
          type: string
        domain:
          type: string
          description: Comma-separated domain names, 25 at most. A URL is cleaned to its domain. Hidden and unknown domains are dropped. With two or more remaining domains, the page spreads its rows across them (up to limit divided by the number of domains for each, never more than limit in total) and returns no next_search_after cursor.
          example: stripe.com,cloudflare.com
        company_name:
          type: string
          description: Comma-separated company names.
          example: Stripe,Acme
        location:
          type: string
          description: Comma-separated ISO 3166-1 alpha-2 country codes.
          example: US,FR
        industry:
          type: string
          description: Comma-separated integer industry codes.
          example: 4,25
        headcount:
          type: string
          description: Comma-separated company-size buckets (e.g. 11-50, 51-200).
          example: 11-50,51-200
        company_type:
          type: string
          description: Comma-separated Hunter company types.
          example: educational,government agency
        founded_year:
          type: string
          description: Comma-separated founding years.
          example: 2015,2016
        technology:
          type: string
          description: Comma-separated technology slugs.
          example: rails,stripe
        department:
          type: string
          description: Comma-separated departments (e.g. executive, sales, marketing).
          example: executive,marketing
        seniority:
          type: string
          description: 'Comma-separated seniority levels: junior, senior, executive.'
          example: senior,executive
        type:
          type: string
          description: 'Comma-separated email types: personal, generic.'
          example: personal
        provenance:
          type: string
          description: 'Comma-separated provenance values: found, inferred.'
          example: found
        job_title:
          type: string
          description: Comma-separated free-text job titles. A person matches when their position matches any of the titles. Independent of department and seniority.
          example: VP of Sales,Head of Growth
        decision_maker:
          allOf:
          - $ref: '#/components/schemas/strict_boolean_filter'
          description: When true, keep only decision-makers.
        verification_status:
          type: string
          description: 'Comma-separated verification statuses: valid, accept_all, unknown.'
          example: valid,accept_all
        required_field:
          type: string
          description: 'Comma-separated fields that every returned person must have (AND): full_name, position, phone_number.'
          example: full_name,position
        min_confidence:
          type: integer
          minimum: 2
          maximum: 100
          description: Minimum email confidence score.
          example: 80
        exclude_already_saved:
          allOf:
          - $ref: '#/components/schemas/strict_boolean_filter'
          description: When true, omit people already saved as leads in your account. This refines a search but does not satisfy the at-least-one-filter requirement on its own.
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
          description: Number of rows to return per page.
        search_after:
          type: string
          description: Opaque pagination cursor from meta.next_search_after. Omit for the first page.
        per_domain:
          allOf:
          - $ref: '#/components/schemas/strict_boolean_filter'
          description: When true, include a per-domain result breakdown in meta.
    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
    multi_domain_search_email:
      type: object
      additionalProperties: false
      required:
      - name
      - position
      - department
      - seniority
      - type
      - decision_maker
      - domain
      - company_name
      - full_name_exists
      - phone_number_exists
      - linkedin_exists
      - verification
      - reveal_handle
      properties:
        name:
          allOf:
          - $ref: '#/components/schemas/nullable_string'
          description: Masked display name — first name plus last initial (e.g. "Ada L."). Null when either name part is missing. The full last name is only returned by the reveal endpoint.
        position:
          $ref: '#/components/schemas/nullable_string'
        department:
          $ref: '#/components/schemas/nullable_string'
        seniority:
          $ref: '#/components/schemas/nullable_string'
        type:
          type: string
          enum:
          - personal
          - generic
        provenance:
          type:
          - string
          - 'null'
          example: found
          description: 'Where the address came from. "found": the address was seen on a public web page. "inferred": it was worked out from the person''s name and the company''s email pattern. "previously_found" is coming: found on a page but not confirmed there in the last 90 days. More values may be added, so treat an unrecognized value as unknown rather than an error. Distinct from `type`, which is the role of the address. Null when no provenance is recorded for the address.'
        decision_maker:
          type: boolean
        domain:
          type: string
          example: example.com
        company_name:
          $ref: '#/components/schemas/nullable_string'
        full_name_exists:
          type: boolean
        phone_number_exists:
          type: boolean
        linkedin_exists:
          type: boolean
        verification:
          type: object
          additionalProperties: false
          required:
          - date
          - status
          properties:
            date:
              $ref: '#/components/schemas/nullable_string'
            status:
              $ref: '#/components/schemas/nullable_string'
        reveal_handle:
          type: string
          description: Opaque, signed handle identifying this row for the reveal endpoint. Never the raw email id.
          example: aAKWnmY9z-P8kCj6sBQjZ8yiYnNSMKb0
    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*$
    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)