openapi: 3.1.0
info:
title: Hunter Enrichment API
description: >
Person, company, and combined enrichment. Turn an email or LinkedIn handle
into a rich person profile (name, role, seniority, social handles, geo), turn
a domain into a company profile (industry, location, technology stack, funding,
metrics), or combine both in a single call.
version: v2
contact:
name: Hunter Support
url: https://hunter.io/contact
servers:
- url: https://api.hunter.io/v2
description: Production
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
- BearerAuth: []
tags:
- name: Enrichment
description: Person, company, and combined enrichment.
paths:
/people/find:
get:
summary: Hunter Enrich Person
description: >
Return a person profile for an email address or LinkedIn handle, including
name, employment, geo, time zone, social handles, and last-seen activity.
operationId: enrichPerson
tags: [Enrichment]
parameters:
- name: email
in: query
schema: { type: string, format: email }
- name: linkedin_handle
in: query
schema: { type: string }
- name: clearbit_format
in: query
description: When true, response is returned in Clearbit-compatible shape for drop-in migration.
schema: { type: boolean }
- $ref: '#/components/parameters/ApiKeyQuery'
responses:
'200':
description: Person profile.
content:
application/json:
schema: { $ref: '#/components/schemas/PersonEnrichmentResponse' }
'400': { $ref: '#/components/responses/Error' }
'404': { $ref: '#/components/responses/Error' }
'429': { $ref: '#/components/responses/Error' }
/companies/find:
get:
summary: Hunter Enrich Company
description: >
Return a company profile for a domain, including industry, location,
technologies, metrics (employees, traffic rank, market cap), funding
rounds, and social handles.
operationId: enrichCompany
tags: [Enrichment]
parameters:
- name: domain
in: query
required: true
schema: { type: string, example: stripe.com }
- name: clearbit_format
in: query
schema: { type: boolean }
- $ref: '#/components/parameters/ApiKeyQuery'
responses:
'200':
description: Company profile.
content:
application/json:
schema: { $ref: '#/components/schemas/CompanyEnrichmentResponse' }
'404': { $ref: '#/components/responses/Error' }
'429': { $ref: '#/components/responses/Error' }
/combined/find:
get:
summary: Hunter Enrich Person And Company
description: >
Combined enrichment. Returns both `person` and `company` blocks for an
email address in a single call.
operationId: enrichCombined
tags: [Enrichment]
parameters:
- name: email
in: query
required: true
schema: { type: string, format: email }
- name: clearbit_format
in: query
schema: { type: boolean }
- $ref: '#/components/parameters/ApiKeyQuery'
responses:
'200':
description: Combined person + company profile.
content:
application/json:
schema: { $ref: '#/components/schemas/CombinedEnrichmentResponse' }
'404': { $ref: '#/components/responses/Error' }
'429': { $ref: '#/components/responses/Error' }
components:
securitySchemes:
ApiKeyQuery: { type: apiKey, in: query, name: api_key }
ApiKeyHeader: { type: apiKey, in: header, name: X-API-KEY }
BearerAuth: { type: http, scheme: bearer }
parameters:
ApiKeyQuery:
name: api_key
in: query
required: true
description: Your Hunter API key.
schema: { type: string }
schemas:
PersonEnrichmentResponse:
type: object
properties:
data:
type: object
properties:
id: { type: string }
name:
type: object
properties:
fullName: { type: string }
givenName: { type: string }
familyName: { type: string }
email: { type: string, format: email }
location: { type: string }
timeZone: { type: string }
geo:
type: object
properties:
city: { type: string }
state: { type: string }
country: { type: string }
lat: { type: number }
lng: { type: number }
employment:
type: object
properties:
domain: { type: string }
name: { type: string }
title: { type: string }
role: { type: string }
seniority: { type: string }
facebook: { type: object, properties: { handle: { type: string } } }
github: { type: object, properties: { handle: { type: string } } }
twitter: { type: object, properties: { handle: { type: string } } }
linkedin: { type: object, properties: { handle: { type: string } } }
gravatar: { type: object, properties: { hash: { type: string } } }
emailProvider: { type: string }
phone: { type: string }
activeAt: { type: string, format: date-time }
inactiveAt: { type: string, format: date-time }
CompanyEnrichmentResponse:
type: object
properties:
data:
type: object
properties:
id: { type: string }
name: { type: string }
legalName: { type: string }
domain: { type: string }
domainAliases: { type: array, items: { type: string } }
site:
type: object
properties:
phoneNumbers: { type: array, items: { type: string } }
emailAddresses: { type: array, items: { type: string } }
category:
type: object
properties:
sector: { type: string }
industry: { type: string }
industryGroup: { type: string }
naicsCode: { type: string }
sicCode: { type: string }
gicsCode: { type: string }
tags: { type: array, items: { type: string } }
description: { type: string }
foundedYear: { type: integer }
location: { type: string }
timeZone: { type: string }
geo:
type: object
properties:
city: { type: string }
state: { type: string }
country: { type: string }
logo: { type: string }
facebook: { type: object, properties: { handle: { type: string } } }
linkedin: { type: object, properties: { handle: { type: string } } }
twitter: { type: object, properties: { handle: { type: string } } }
crunchbase: { type: object, properties: { handle: { type: string } } }
instagram: { type: object, properties: { handle: { type: string } } }
type: { type: string }
ticker: { type: string }
metrics:
type: object
properties:
alexaUsRank: { type: integer }
alexaGlobalRank: { type: integer }
trafficRank: { type: string }
employees: { type: integer }
employeesRange: { type: string }
marketCap: { type: integer }
raised: { type: integer }
annualRevenue: { type: integer }
tech: { type: array, items: { type: string } }
techCategories: { type: array, items: { type: string } }
fundingRounds:
type: array
items:
type: object
properties:
amount: { type: integer }
currency: { type: string }
series: { type: string }
announcedDate: { type: string, format: date }
CombinedEnrichmentResponse:
type: object
properties:
data:
type: object
properties:
person: { $ref: '#/components/schemas/PersonEnrichmentResponse/properties/data' }
company: { $ref: '#/components/schemas/CompanyEnrichmentResponse/properties/data' }
Error:
type: object
properties:
errors:
type: array
items:
type: object
properties:
id: { type: string }
code: { type: integer }
details: { type: string }
responses:
Error:
description: Error response.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }