Hunter Verifier API

openapi: 3.2.0
info:
  title: Hunter Verifier 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: Verifier
paths:
  /email-verifier:
    get:
      operationId: verifyEmail
      summary: Verify an email address
      description: Check the deliverability of an email address. A `valid` or `accept_all` email address is also saved automatically to your leads, and a lead you already have gets the new verification result. 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:
      - Verifier
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - name: email
        in: query
        required: true
        schema:
          type: string
      - name: domain_metadata
        in: query
        description: Include metadata about the email domain when set to any non-empty value. An empty value or omission disables it.
        schema:
          type: string
          example: '1'
      responses:
        '200':
          description: Deliverability status and verification checks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email_verifier_response'
        '202':
          description: Verification is still in progress and can be polled again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pending_envelope'
        '222':
          description: Verification failed for reasons outside Hunter's control and can be retried later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '451':
          description: The claimed email address cannot be processed for privacy reasons.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        default:
          $ref: '#/components/responses/Error'
  /email-insight:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: email
      in: query
      description: Email address to inspect.
      schema:
        type: string
        format: email
    get:
      operationId: getEmailInsight
      summary: Get deliverability insight for an email address
      tags:
      - Verifier
      security: []
      responses:
        '200':
          description: Get deliverability insight for an email address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $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:
    email_verifier_response:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - status
          - score
          - email
          - regexp
          - gibberish
          - disposable
          - webmail
          - mx_records
          - smtp_server
          - smtp_check
          - accept_all
          - block
          - verification
          - sources
          - result
          - _deprecation_notice
          properties:
            status:
              type: string
            score:
              type: integer
            email:
              type: string
              format: email
            regexp:
              type: boolean
            gibberish:
              type: boolean
            disposable:
              type: boolean
            webmail:
              type: boolean
            mx_records:
              type: boolean
            smtp_server:
              type: boolean
            smtp_check:
              type: boolean
            accept_all:
              type: boolean
            block:
              type: boolean
            verification:
              $ref: '#/components/schemas/verification_summary'
            sources:
              type: array
              items:
                $ref: '#/components/schemas/source'
            result:
              type: string
            _deprecation_notice:
              type: string
        meta:
          type: object
          additionalProperties: false
          required:
          - params
          properties:
            domain:
              type: string
            company_name:
              type: string
            following_domain:
              type: boolean
            webmail:
              type: boolean
            params:
              type: object
              additionalProperties: false
              required:
              - email
              properties:
                email:
                  type: string
    generic_resource_response:
      type: object
      additionalProperties: true
      description: Generic envelope for V2 resource operations whose detailed schema is not yet in the contract.
    nullable_integer:
      type:
      - integer
      - 'null'
    pending_envelope:
      type: object
      additionalProperties: false
      required:
      - meta
      properties:
        data:
          type: object
          additionalProperties: false
        meta:
          type: object
          additionalProperties: false
          required:
          - params
          - message
          properties:
            params:
              type: object
              additionalProperties: false
              required:
              - email
              properties:
                email:
                  type: string
            message:
              type: string
    error_response:
      oneOf:
      - $ref: '#/components/schemas/standard_error_response'
      - $ref: '#/components/schemas/legacy_error_response'
    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
    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
    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'
    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)