Hunter Combined Enrichment API

openapi: 3.1.0
info:
  title: Hunter Account Combined 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: Combined Enrichment
  description: Merge person and company enrichment for a single email address.
paths:
  /combined/find:
    get:
      operationId: combinedEnrichment
      summary: Hunter Combined Enrichment
      description: Merges person and company information for a single email address, returning enriched records combining both datasets.
      tags:
      - Combined Enrichment
      parameters:
      - name: email
        in: query
        required: true
        description: Email address to enrich with both person and company data.
        schema:
          type: string
          format: email
      - name: clearbit_format
        in: query
        description: Format response to match the Clearbit schema.
        schema:
          type: boolean
      responses:
        '200':
          description: Successful combined enrichment response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      person:
                        $ref: '#/components/schemas/PersonEnrichment'
                      company:
                        $ref: '#/components/schemas/CompanyEnrichment'
                  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:
    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: []
    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'
    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
    CompanyEnrichment:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the company record.
          example: abc123
        name:
          type:
          - string
          - 'null'
          description: Company name.
          example: Example Title
        legalName:
          type:
          - string
          - 'null'
          description: Legal name of the company.
          example: example_value
        domain:
          type: string
          description: Company domain name.
          example: example_value
        domainAliases:
          type: array
          items:
            type: string
          description: Alternate domain names.
          example: []
        site:
          type: object
          properties:
            phoneNumbers:
              type: array
              items:
                type: string
            emailAddresses:
              type: array
              items:
                type: string
          example: example_value
        category:
          type: object
          description: Industry classification.
          properties:
            sector:
              type:
              - string
              - 'null'
            industryGroup:
              type:
              - string
              - 'null'
            industry:
              type:
              - string
              - 'null'
            subIndustry:
              type:
              - string
              - 'null'
            gicsCode:
              type:
              - string
              - 'null'
            sicCode:
              type:
              - string
              - 'null'
            sic4Codes:
              type: array
              items:
                type: string
            naicsCode:
              type:
              - string
              - 'null'
            naics6Codes:
              type: array
              items:
                type: string
            naics6Codes2022:
              type: array
              items:
                type: string
          example: example_value
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the company.
          example: []
        description:
          type:
          - string
          - 'null'
          description: Company description.
          example: A sample description.
        foundedYear:
          type:
          - integer
          - 'null'
          description: Year the company was founded.
          example: example_value
        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/CompanyGeoLocation'
        logo:
          type:
          - string
          - 'null'
          format: uri
          description: Company logo URL.
          example: https://www.example.com
        facebook:
          type: object
          properties:
            handle:
              type:
              - string
              - 'null'
            likes:
              type:
              - integer
              - 'null'
          example: example_value
        linkedin:
          type: object
          properties:
            handle:
              type:
              - string
              - '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'
            location:
              type:
              - string
              - 'null'
            site:
              type:
              - string
              - 'null'
            avatar:
              type:
              - string
              - 'null'
          example: example_value
        crunchbase:
          type: object
          properties:
            handle:
              type:
              - string
              - 'null'
          example: example_value
        emailProvider:
          type:
          - string
          - 'null'
          description: Email service provider.
          example: user@example.com
        type:
          type:
          - string
          - 'null'
          description: Company type.
          example: example_value
        company_type:
          type:
          - string
          - 'null'
          description: Entity type classification.
          example: example_value
        ticker:
          type:
          - string
          - 'null'
          description: Stock ticker symbol.
          example: example_value
        identifiers:
          type: object
          properties:
            usEIN:
              type:
              - string
              - 'null'
              description: US Employer Identification Number.
          example: example_value
        phone:
          type:
          - string
          - 'null'
          description: Primary phone number.
          example: example_value
        metrics:
          type: object
          properties:
            alexaUsRank:
              type:
              - integer
              - 'null'
            alexaGlobalRank:
              type:
              - integer
              - 'null'
            trafficRank:
              type:
              - string
              - 'null'
            employees:
              type:
              - string
              - 'null'
              description: Estimated employee count or range.
            marketCap:
              type:
              - number
              - 'null'
            raised:
              type:
              - number
              - 'null'
              description: Total funding raised.
            annualRevenue:
              type:
              - number
              - 'null'
            estimatedAnnualRevenue:
              type:
              - number
              - 'null'
            fiscalYearEnd:
              type:
              - string
              - 'null'
          example: example_value
        indexedAt:
          type:
          - string
          - 'null'
          format: date
          description: Date when the record was last indexed.
          example: '2026-01-15'
        tech:
          type: array
          items:
            type: string
          description: Technologies used by the company.
          example: []
        techCategories:
          type: array
          items:
            type: string
          description: Categories of technologies used.
          example: []
        parent:
          type: object
          properties:
            domain:
              type:
              - string
              - 'null'
          example: example_value
        ultimateParent:
          type: object
          properties:
            domain:
              type:
              - string
              - 'null'
          example: example_value
    CompanyGeoLocation:
      type: object
      properties:
        streetNumber:
          type:
          - string
          - 'null'
          example: example_value
        streetName:
          type:
          - string
          - 'null'
          example: example_value
        subPremise:
          type:
          - string
          - 'null'
          example: example_value
        streetAddress:
          type:
          - string
          - 'null'
          example: example_value
        city:
          type:
          - string
          - 'null'
          example: example_value
        postalCode:
          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
  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.