Hunter Account API

openapi: 3.2.0
info:
  title: Hunter Account 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: Account
paths:
  /account:
    get:
      operationId: getAccount
      summary: Get account details and usage
      description: 'When `data.requests.credits` is present, the team has a single credits pool: plan with `credits.remaining`. A search costs 1 credit and a verification 0.5 credit. `searches` and `verifications` are then approximate views of the same pool (rounded down, with request-pack usage counted per type), not separate quotas. Without `credits`, `searches` and `verifications` are separate quotas.'
      tags:
      - Account
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Account, plan, team, and quota details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/account_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    put:
      operationId: updateAccount
      summary: Update account details
      tags:
      - Account
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      responses:
        '204':
          description: Account updated, no content.
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /account-stats:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: getAccountStats
      summary: Get account profile summary
      tags:
      - Account
      responses:
        '200':
          description: Account profile summary with identity, plan, and most used source.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '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:
    account_response:
      type: object
      additionalProperties: false
      required:
      - data
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - first_name
          - last_name
          - email
          - plan_name
          - plan_level
          - reset_date
          - team_id
          - requests
          - calls
          properties:
            first_name:
              $ref: '#/components/schemas/nullable_string'
            last_name:
              $ref: '#/components/schemas/nullable_string'
            email:
              type: string
              format: email
            plan_name:
              type: string
            plan_level:
              type: integer
            reset_date:
              type: string
              format: date
            team_id:
              type: integer
            requests:
              type: object
              additionalProperties: false
              required:
              - searches
              - verifications
              properties:
                credits:
                  $ref: '#/components/schemas/usage_bucket'
                searches:
                  $ref: '#/components/schemas/usage_bucket'
                verifications:
                  $ref: '#/components/schemas/usage_bucket'
            calls:
              type: object
              additionalProperties: false
              required:
              - _deprecation_notice
              - used
              - available
              properties:
                _deprecation_notice:
                  type: string
                used:
                  type: number
                available:
                  type: number
    generic_resource_response:
      type: object
      additionalProperties: true
      description: Generic envelope for V2 resource operations whose detailed schema is not yet in the contract.
    error_response:
      oneOf:
      - $ref: '#/components/schemas/standard_error_response'
      - $ref: '#/components/schemas/legacy_error_response'
    usage_bucket:
      type: object
      additionalProperties: false
      required:
      - used
      - available
      - remaining
      properties:
        used:
          type: number
        available:
          type: number
        remaining:
          type: number
        over_quota:
          type: number
    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
    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)