openapi: 3.1.0
info:
  title: Hunter Account Email Enrichment API
  description: Hunter is an email finding and verification service that helps find professional email addresses associated with a domain and verify email deliverability. The API provides domain search, email finder, email verifier, email count, account information, leads management, leads lists, campaigns, discover, enrichment, and logo retrieval capabilities.
  version: 2.0.0
  termsOfService: https://hunter.io/terms
  contact:
    name: Hunter Support
    url: https://hunter.io/contact
    email: support@hunter.io
  license:
    name: Proprietary
    url: https://hunter.io/terms
servers:
- url: https://api.hunter.io/v2
  description: Hunter API v2 Production
security:
- apiKeyQuery: []
- apiKeyHeader: []
- bearerAuth: []
tags:
- name: Email Enrichment
  description: Enrich personal information linked to an email or LinkedIn profile.
paths:
  /people/find:
    get:
      operationId: emailEnrichment
      summary: Hunter Email Enrichment
      description: Returns comprehensive personal information linked to an email address or LinkedIn profile. Provides enriched data points about the person including employment, social profiles, and location.
      tags:
      - Email Enrichment
      parameters:
      - name: email
        in: query
        description: Email address to enrich. Required if linkedin_handle is not provided.
        schema:
          type: string
          format: email
      - name: linkedin_handle
        in: query
        description: LinkedIn profile handle. Required if email is not provided.
        schema:
          type: string
      - name: clearbit_format
        in: query
        description: Format response to match the Clearbit schema.
        schema:
          type: boolean
      responses:
        '200':
          description: Successful email enrichment response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PersonEnrichment'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '451':
          $ref: '#/components/responses/UnavailableForLegalReasons'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    UnavailableForLegalReasons:
      description: Cannot process this person's data due to legal restrictions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Usage limit exceeded or rate limited.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid parameters or missing required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    GeoLocation:
      type: object
      properties:
        city:
          type:
          - string
          - 'null'
          example: example_value
        state:
          type:
          - string
          - 'null'
          example: example_value
        stateCode:
          type:
          - string
          - 'null'
          example: example_value
        country:
          type:
          - string
          - 'null'
          example: example_value
        countryCode:
          type:
          - string
          - 'null'
          example: example_value
        lat:
          type:
          - number
          - 'null'
          example: example_value
        lng:
          type:
          - number
          - 'null'
          example: example_value
    Meta:
      type: object
      properties:
        params:
          type: object
          description: The parameters used in the request.
          example: example_value
    PersonEnrichment:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the person record.
          example: abc123
        name:
          type: object
          properties:
            fullName:
              type:
              - string
              - 'null'
            givenName:
              type:
              - string
              - 'null'
            familyName:
              type:
              - string
              - 'null'
          example: Example Title
        email:
          type: string
          format: email
          description: Email address.
          example: user@example.com
        location:
          type:
          - string
          - 'null'
          description: Location description.
          example: example_value
        timeZone:
          type:
          - string
          - 'null'
          description: Time zone name.
          example: example_value
        utcOffset:
          type:
          - number
          - 'null'
          description: UTC offset in hours.
          example: example_value
        geo:
          $ref: '#/components/schemas/GeoLocation'
        bio:
          type:
          - string
          - 'null'
          description: Short biography.
          example: example_value
        site:
          type:
          - string
          - 'null'
          description: Personal website URL.
          example: example_value
        avatar:
          type:
          - string
          - 'null'
          description: Avatar image URL.
          example: example_value
        employment:
          type: object
          properties:
            domain:
              type:
              - string
              - 'null'
            name:
              type:
              - string
              - 'null'
            title:
              type:
              - string
              - 'null'
            role:
              type:
              - string
              - 'null'
            subRole:
              type:
              - string
              - 'null'
            seniority:
              type:
              - string
              - 'null'
          example: example_value
        facebook:
          type: object
          properties:
            handle:
              type:
              - string
              - 'null'
          example: example_value
        github:
          type: object
          properties:
            handle:
              type:
              - string
              - 'null'
            id:
              type:
              - integer
              - 'null'
            avatar:
              type:
              - string
              - 'null'
            company:
              type:
              - string
              - 'null'
            blog:
              type:
              - string
              - 'null'
            followers:
              type:
              - integer
              - 'null'
            following:
              type:
              - integer
              - 'null'
          example: example_value
        twitter:
          type: object
          properties:
            handle:
              type:
              - string
              - 'null'
            id:
              type:
              - integer
              - 'null'
            bio:
              type:
              - string
              - 'null'
            followers:
              type:
              - integer
              - 'null'
            following:
              type:
              - integer
              - 'null'
            statuses:
              type:
              - integer
              - 'null'
            favorites:
              type:
              - integer
              - 'null'
            location:
              type:
              - string
              - 'null'
            site:
              type:
              - string
              - 'null'
            avatar:
              type:
              - string
              - 'null'
          example: example_value
        linkedin:
          type: object
          properties:
            handle:
              type:
              - string
              - 'null'
          example: example_value
        fuzzy:
          type: boolean
          description: Whether the match was fuzzy.
          example: true
        emailProvider:
          type:
          - string
          - 'null'
          description: Email service provider.
          example: user@example.com
        indexedAt:
          type:
          - string
          - 'null'
          format: date
          description: Date when the record was last indexed.
          example: '2026-01-15'
        phone:
          type:
          - string
          - 'null'
          description: Phone number.
          example: example_value
        activeAt:
          type:
          - string
          - 'null'
          format: date
          description: Date when the person was last active.
          example: '2026-01-15'
        inactiveAt:
          type:
          - string
          - 'null'
          format: date
          description: Date when the person became inactive.
          example: '2026-01-15'
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Error identifier code.
              code:
                type: integer
                description: HTTP status code.
              details:
                type: string
                description: Human-readable error message.
          example: []
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as a query parameter.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key passed via the X-API-KEY header.
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token in the Authorization header.