# Get Credit Balance
Source: https://docs.fullenrich.com/api/v2/account/credits/get
api/v2/reference/openapi.yml GET /account/credits
This endpoint provides the current balance of credits available in your workspace.
# Check If API Key Is Valid
Source: https://docs.fullenrich.com/api/v2/account/keys/verify/get
api/v2/reference/openapi.yml GET /account/keys/verify
This endpoint checks if your API key is valid.
# Look Up Company
Source: https://docs.fullenrich.com/api/v2/company/lookup/post
api/v2/reference/openapi.yml POST /company/lookup
Look up a single company using its identifiers (domain, or professional network URL/ID). Returns the best matching company.
The Company Look Up endpoint returns a single company when you already know which one you are looking for. Provide an identifier and the API matches the best corresponding company.
You can look up a company by its **domain** or its **professional network URL or ID** for an exact match.
The response has the same shape as [Search Company](/api/v2/company/search/post), but always contains at most one company.
[Search API pricing](/api/v2/general/credit)
# Search Company
Source: https://docs.fullenrich.com/api/v2/company/search/post
api/v2/reference/openapi.yml POST /company/search
Search for companies based on various filters. Multiple filters within the same field are combined with AND logic.
The Company Search endpoint allows you to search for companies by size, industry, location, founding year, specialties, and more. It is designed to help you build clean company lists for prospecting, enrichment, or market analysis.
**How filters work**
If you filter by company industries \["Technology, Information and Internet", "Financial Services"] and company locations \["France", "United States"], the API returns results where the company industry is either Technology, Information and Internet or Financial Services, AND the company location is either France or United States.
In other words, a result must satisfy at least one value in every filter category you specify.
Within a category, values act as OR: a result matches if it fits any of the values. Across categories, the logic is AND: a result must match all categories to be returned.
**If you want to retrieve one specific company,** you can search directly using its professional network URL or domain for an exact match.
[Search API pricing](/api/v2/general/credit)
For a full list of supported filters and accepted values (industries, company types, seniority levels, etc.)
For a full list of supported filters and accepted values (industries, company types, seniority levels, etc.)
# Get Enrichment Result
Source: https://docs.fullenrich.com/api/v2/contact/enrich/bulk/get
api/v2/reference/openapi.yml GET /contact/enrich/bulk/{enrichment_id}
Use this endpoint to retrieve the result from an enrich.
You don’t need to use this endpoint if you are using a webhook. Using a webhook is the method we recommend to get the result as soon as the enrichment is done.
# Start Bulk Enrichment
Source: https://docs.fullenrich.com/api/v2/contact/enrich/bulk/post
api/v2/reference/openapi.yml POST /contact/enrich/bulk
Learn how to authenticate your API requests with your API key.
Use this endpoint to find the contact information of any B2B person:
* Work email (1 credit)
* Mobile phone number (10 credits)
* Personal Email (3 credits)
#### Input needed
To enrich a contact, you must provide either:
1. `first_name` + `last_name` & `company` (domain or company\_name)
2. `linkedin_url`
For the best results, provide as much information as possible. Including a LinkedIn URL can improve enrichment rates by +5–20% for emails and +10–60% for mobile phone numbers.
If you pass a `linkedin_url`, we will also return a full contact and company profile (job title, location, headcount, etc.).
#### Practical tips
You can enrich up to 100 contacts in bulk. If you want to enrich only 1 contact, you can pass only 1 contact in the list.
All enrichments started on the API are visible on your FullEnrich dashboard. It is good practice to use a readable 'name' for each enrichment. This way, you can easily search through them. For instance, if you are enriching just one contact, you might name your enrichment 'Firstname Lastname'.
To pass specific properties, utilize the 'custom' field by passing an object. For example, if you are enriching a contact from your CRM, include the CRM 'contact\_id' in the custom object. This allows you to reference the contact\_id when you receive the result on your webhook. The custom value should be a cast as a string (number will return an error)
To retrieve the results of your enrichment, you can either provide a **webhook URL** \[recommended] or call the **GET /bulk/enrichment\_id** endpoint \[not recommended].
Learn how to receive results in real-time, set up per-contact webhooks, and track requests with custom fields.
# Get Reverse Email Result
Source: https://docs.fullenrich.com/api/v2/contact/reverse/email/bulk/get
api/v2/reference/openapi.yml GET /contact/reverse/email/bulk/{enrichment_id}
Use this endpoint to retrieve the result from a reverse email lookup.
Use this endpoint to retrieve the result from a reverse email lookup.
You don’t need to use this endpoint if you are using a webhook. Using a webhook is the method we recommend to get the result as soon as the enrichment is done.
# Reverse Email Lookup
Source: https://docs.fullenrich.com/api/v2/contact/reverse/email/bulk/post
api/v2/reference/openapi.yml POST /contact/reverse/email/bulk
Learn how to authenticate your API requests with your API key.
Get the full Person and Company profile from an email. This endpoint works with:
* Work emails
* Personal emails
If we find who's behind the email, **1** credit will be used.
Learn how to receive results in real-time, set up per-contact webhooks, and track requests with custom fields.
# Authentication
Source: https://docs.fullenrich.com/api/v2/general/authentication
To ensure the security of your data and to authenticate requests, FullEnrich API uses Bearer Authentication. This means that you need to include a valid API key in the Authorization header of each request you make to our API.
Each request to our API endpoints must include this authorization header.
Here's how to include your API key in your request:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
Your API key can be found on your API Dashboard
Click here to grab your API Key
Be sure to replace YOUR\_API\_KEY with the actual API key from your dashboard. Without a valid API key in your request, you will not be able to access the API endpoints and will receive a 401 Unauthorized response.
Keep your API key secure and do not share it publicly.
If you suspect that your API key has been compromised, you should regenerate it immediately from your account dashboard to prevent unauthorized access.
# Credits & Testing Tips
Source: https://docs.fullenrich.com/api/v2/general/credit
## How credits work
The use of credits is the same on the API as it is on the rest of the platform.
Credits are only consumed when we actually find a result.
**Contact Data Enrichment**\*– find email or phone numbers\*
* If a Deliverable, High Probability, or Catch-all email is found, **1** credit will be used.
* If a mobile phone is found, **10** credits will be used.
* If a valid personal email is found, **3** credits will be used.
*(For custom plans, this ratio might be different)*
**Reverse Email Lookup** – Find the person and company behind an email
* If we find who's behind an email, **1** credit will be used
**Search API** – Search for people or companies
* Each person or company returned costs **0.25** credit (once a person/company have been exported once via the UI, or the API, it does not cost anything to export it again)\
\
*For high-volume search use cases (hundreds of thousands or millions of searches), we offer custom pricing models that make large-scale search economically viable. Contact our team to discuss.*
## Will I be charged for duplicate contacts?
**Short answer: No. (with a but)**
We don't typically charge for re-enriching a previously enriched contact, as our system deduplicates based on the information you provide.
However, there are exceptions. If the input information differs, such as variations in the first name, last name, company domain, LinkedIn profile URL, etc., we will not successfully deduplicate.
**Also we do not deduplicate contacts within the same bulk.**
Finally, **simultaneous enrichment requests for the same contact will prevent deduplication**, as they require one enrichment to be completed before we can deduplicate.
(Custom fields do not affect deduplication)
## How long do we store the data?
For GDPR compliance, we only store enrichment data for **3 months**.
If you try to fetch results with the same **Enrichment ID** after 3 months, you'll get an error.
* If you re-enrich the same contact **within 3 months**, we'll return the result from your history, creating a new enrichment but costing **0 credits** (see section above about duplicate contacts).
* If you re-enrich the same contact **after 3 months**, we'll launch a fresh enrichment. This will create a new enrichment and will **cost credits**.
## Setting up low credit alerts
You can set up a low credit alert directly from your FullEnrich dashboard to avoid running out of credits and blocking new enrichments. It's in the settings of the webapp: [**https://app.fullenrich.com/app/settings/credits/alerts/**](https://app.fullenrich.com/app/settings/credits/alerts/)
We recommend enabling this alert for production use to stay notified before your credits run out and keep your enrichment workflow running smoothly.
## Tips for testing ✨
We have hard-coded some contacts from the FullEnrich team, such as
```json theme={null}
{
"first_name": "Grégoire",
"last_name": "Démogé",
"domain": "fullenrich.com",
"company_name": "FullEnrich",
"linkedin_url": "https://www.linkedin.com/in/demoge/"
}
```
These use **0 credits**, allowing you to test without spending any credits. (Be careful to use this exact data; otherwise, it might not work.)
Also, since:
* You won't be charged for duplicate contacts
* Previously enriched contacts are pulled from memory instead of doing the waterfall process again (takes less time)
**We suggest using the same contact for most of your testing:** Enrichment will be fast, and won't cost any credits.
A quick way to check the result endpoint and troubleshoot is to use a webhook URL from [**webhook.site**](http://webhook.site). (free service)
# Data Dictionary
Source: https://docs.fullenrich.com/api/v2/general/data-dictionary
Every data point you get from FullEnrich — across Search, Enrichment, and Reverse Email.
This is the complete list of **output** data points FullEnrich returns. Each row
is one field: its API name (dot notation relative to its parent object), type,
what it means, and an example. For the accepted **filter** values, see
[Accepted Filter Values](/api/v2/general/enums).
# 👤 People
### 🪪 Identity
| Data point | API field | Type | Description | Example |
| -------------------------------- | ------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Full name | `full_name` | string | First and last name | `Greg Démogé` |
| First name | `first_name` | string | First name | `Greg` |
| Last name | `last_name` | string | Last name | `Démogé` |
| Headline | `headline` | string | Short professional tagline written by the person on their professional network profile | `Co-founder & CPO at FullEnrich \| B2B Data & Enrichment` |
| Description | `description` | string | Free-text summary written by the person in the about section of their professional network profile (not always present) | `Building FullEnrich to make B2B contact data reliable…` |
| City | `location.city` | string | City | `San Francisco` |
| Region / state | `location.region` | string | Region or state | `California` |
| Country | `location.country` | string | Country name | `United States` |
| Country code | `location.country_code` | string | ISO 3166-1 alpha-2 code | `US` |
| Professional network URL | `social_profiles.professional_network.url` | string | Profile URL | `https://www.linkedin.com/in/demoge` |
| Professional network handle | `social_profiles.professional_network.handle` | string | Profile handle | `demoge` |
| Professional network id | `social_profiles.professional_network.id` | integer | Numeric profile id | `583778722` |
| Professional network connections | `social_profiles.professional_network.connection_count` | integer | Network size | `500` |
| Language | `languages[].language` | string | Language spoken | `english` |
| Language proficiency | `languages[].proficiency` | string (enum) | Proficiency level | `FULL_PROFESSIONAL` |
### 📇 Verified contact info
Returned by **Enrichment** and **Reverse Email**. Only deliverable/valid results are returned, so any of these may be absent for a given contact.
| Data point | API field | Type | Description | Example |
| --------------------- | --------------------------------------- | ------------- | ------------------------------------------ | --------------------------------------- |
| Work email | `contact_info.work_emails[].email` | string | Verified professional email | `greg@fullenrich.com` |
| Work email status | `contact_info.work_emails[].status` | string (enum) | Deliverability status | `DELIVERABLE` |
| Personal email | `contact_info.personal_emails[].email` | string | Verified personal email | `greg.demoge@gmail.com` |
| Personal email status | `contact_info.personal_emails[].status` | string (enum) | Deliverability status | `DELIVERABLE` |
| Mobile number | `contact_info.phones[].number` | string | Verified mobile number, worldwide coverage | `+1 415 555 0132` · `+33 6 12 34 56 78` |
| Mobile region | `contact_info.phones[].region` | string | ISO 3166-1 alpha-2 code of the number | `US` · `FR` |
We also return `most_probable_work_email`, `most_probable_personal_email`, and
`most_probable_phone` — the single best result for each type, matched by domain
proximity and bounce rate (`INVALID` emails excluded). For the phones above, the
US number is the most probable (`most_probable_phone` → `+1 415 555 0132`). Each
has the same sub-fields as the corresponding array element.
### 💼 Current & past roles
Returned under `employment.current` (single object) and `employment.all[]` (full
history). **Each field below exists per experience.**
| Data point | API field | Type | Description | Example |
| ---------------- | ------------------------------ | ----------------- | --------------------------------------------------------------- | ----------------------------------------- |
| Job title | `title` | string | Job title | `Co-founder & CPO` |
| Seniority | `seniority` | string (enum) | Seniority level | `Founder` |
| Job function | `job_functions[].function` | string (enum) | Function category | `Executive & Leadership` |
| Sub-function | `job_functions[].sub_function` | string (enum) | Role within the function | `Founder/Owner` |
| Role description | `description` | string | Declarative description of the role (not always present) | `Leading product and data at FullEnrich…` |
| Company | `company` | object | Employer — full company profile, see [Company](#-company) | `FullEnrich` |
| Start date | `start_at` | string (ISO 8601) | Employment start, `YYYY-MM-DDTHH:MM:SSZ` | `2024-01-01T00:00:00Z` |
| End date | `end_at` | string (ISO 8601) | Employment end — **only for past roles** (omitted when current) | `2023-12-31T00:00:00Z` |
| Is current | `is_current` | boolean | Whether this is the current employment | `true` |
### 🎓 Education & skills
| Data point | API field | Type | Description | Example |
| --------------- | -------------------------- | ----------------- | ---------------------------- | --------------------------------------------------- |
| School | `educations[].school_name` | string | Institution | `Stanford University` |
| Degree | `educations[].degree` | string | Degree | `MS` |
| Education start | `educations[].start_at` | string (ISO 8601) | Start date | `2015-09-01T00:00:00Z` |
| Education end | `educations[].end_at` | string (ISO 8601) | End date | `2019-06-30T00:00:00Z` |
| Skills | `skills[]` | string array | Professional declared skills | `Design Strategy, Interaction Design, Lean Startup` |
# 🏢 Company
Every person record embeds the **full company profile** for their current (and
past) employers, under `employment.current.company` / `employment.all[].company`.
Company Search and Company Lookup return the same object.
### 🏷️ Identity
| Data point | API field | Type | Description | Example |
| ------------------------------ | ------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Company id | `id` | string (uuid) | Unique company identifier | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |
| Company name | `name` | string | Legal or brand name | `FullEnrich` |
| Domain | `domain` | string | Company domain | `fullenrich.com` |
| Website | `website` | string | Company website URL as declared by the company — may differ from `domain` (subdomain, path, tracking parameters). Not always present | `https://www.fullenrich.com` |
| Description | `description` | string | Company description | `Waterfall enrichment across 20+ vendors to find verified emails and phone numbers.` |
| Logo URL | `logo_url` | string | Company logo hosted by FullEnrich, built from the professional network handle | `https://app.fullenrich.com/logo/company/handle/fullenrich` |
| Professional network id | `social_profiles.professional_network.id` | integer | Numeric company id | `98444201` |
| Professional network handle | `social_profiles.professional_network.handle` | string | Company page handle | `fullenrich` |
| Professional network URL | `social_profiles.professional_network.url` | string | Company page URL | `https://www.linkedin.com/company/fullenrich` |
| Professional network followers | `social_profiles.professional_network.connection_count` | integer | Followers count | `24507` |
### 📊 Firmographics
| Data point | API field | Type | Description | Example |
| --------------- | ------------------------ | ------------- | ------------------------------------------------------------ | -------------------------------- |
| Industry | `industry.main_industry` | string (enum) | Primary industry (standard industry taxonomy, 200+ values) | `Software Development` |
| Specialties | `specialties[]` | string array | Declarative tags and focus areas | `B2B data, Email & phone finder` |
| Company type | `company_type` | string (enum) | Public, private, nonprofit… | `Privately Held` |
| Headcount | `headcount` | integer | Exact employee count (may be `0` even when a range is known) | `65` |
| Headcount range | `headcount_range` | string (enum) | Size bracket | `11-50` |
| Year founded | `year_founded` | integer | Founding year (`0` when unknown) | `2023` |
### 📍 Location
| Data point | API field | Type | Description | Example |
| ----------------- | ------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------- |
| HQ street | `locations.headquarters.line1` | string | Street address | `1885 Mission St` |
| HQ address line 2 | `locations.headquarters.line2` | string | Full location string | `San Francisco, California 94103, US` |
| HQ city | `locations.headquarters.city` | string | City | `San Francisco` |
| HQ region | `locations.headquarters.region` | string | State or region | `California` |
| HQ country | `locations.headquarters.country` | string | Country name | `United States` |
| HQ country code | `locations.headquarters.country_code` | string | ISO 3166-1 alpha-2 code | `US` |
| Offices | `locations.offices[].{line1, line2}` | array | Additional offices — **raw address lines only** (no parsed city/region); can be `null` or empty | `111 8th Ave` · `New York, NY 10011, US` |
# Accepted values
Enum value lists are maintained in one place — they are not duplicated here:
| Field | Source of truth |
| ---------------------------------------------------------------------- | --------------------------------------------------------- |
| Seniority, Job function & sub-function, Company industry, Company type | [Accepted Filter Values](/api/v2/general/enums) |
| Email status (`work/personal email status`) | [Email Verification Status](/api/v2/general/email-status) |
Two short sets that have no dedicated page:
* **Headcount range:** `1-10` · `11-50` · `51-200` · `201-500` · `501-1000` · `1001-5000` · `5001-10000` · `10001+`
* **Language proficiency:** `NATIVE_OR_BILINGUAL` · `FULL_PROFESSIONAL` · `PROFESSIONAL_WORKING` · `LIMITED_WORKING` · `ELEMENTARY`
# Email Verification Status
Source: https://docs.fullenrich.com/api/v2/general/email-status
Every email we return undergoes a triple verification process to ensure its validity. If an email is flagged as invalid by one provider, we continue checking until a valid email is confirmed or all options are exhausted.
### Email Statuses
We categorize emails into four statuses:
**DELIVERABLE**: 2% bounce rate.
**HIGH\_PROBABILITY**: 9% bounce rate. (those are emails that are catch-all, but likely valid based on our triple verification process)
**CATCH\_All**: higher bounce rate than high\_probability.
**INVALID**: Very likely to bounce.
### "most\_probable\_work\_email" Field
This field returns the work email with the lowest bounce rate. If multiple valid emails are found, we prefer the one with a domain closest to the user-entered domain. INVALID emails are excluded from this field.
### Email Status in the Response
The email object includes a `status` field that indicates the verification status of that email.
***
If you want more details about the triple verification process, here is a link to the Helpdesk.
[https://help.fullenrich.com/en/articles/9541151-how-our-email-verification-works](https://help.fullenrich.com/en/articles/9541151-how-our-email-verification-works)
# Accepted Filter Values
Source: https://docs.fullenrich.com/api/v2/general/enums
List of enums included in the output that can also be used as filters
```
Administrative
Data Entry
Executive Assistant
General Administrative
Office Management
Receptionist
Records Management
Scheduling
Virtual Assistant
Agriculture & Environment
Agriculture/Landscaping
ESG & Sustainability
Veterinary
Construction & Trades
Carpenter
Electrician
General Contractor
HVAC
Heavy Equipment Operators
Mason
Painter
Plumber
Roofer
Safety/HSE
Site Supervisor
Surveyor
Traditional Crafts
Welder
Consulting & Advisory
Advisors
Coaching
ESG & Sustainability
Financial Consulting
HR Consulting
IT Consulting
Independent Consulting
Management Consulting
Operations Consulting
Strategy Consulting
Customer Service
Call Center
Client Services
Customer Experience
Customer Operations
Customer Support
General Customer Service
Help Desk
IT Support/Help Desk
Technical Support
Design
Architecture
Brand Design
Creative/Design
Fashion Design
Graphic Design
Illustration
Industrial Design
Interaction Design
Interior Design
Motion Design
Photography
UI/UX Design
Visual Design
Education
Academia
Curriculum Development
Early Childhood Education
Education - Teaching
Educational Administration
Higher Education
K-12 Teaching
Library Services
Private Tutoring
Special Education
Training & Facilitation
Energy & Utilities
Energy/Mining
Mining
Nuclear
Oil & Gas
Power Generation
Renewable Energy
Utilities Operations
Entertainment & Gaming
Cultural Institutions
Sports
Video Games
Executive & Leadership
Board Member
Entrepreneur
Executive/C-Level
Finance Leadership
Founder/Owner
General Manager
HR Leadership
Managing Director
Marketing Leadership
Operations Leadership
Partner
President
Product Leadership
Sales Leadership
Supervisory/Team Lead
Technical Leadership
VP/Executive
Finance
Accounting
Audit
Banking/Finance
Billing & Collections
Controllers
Corporate Finance
Credit Analysis
ESG & Sustainability
Finance Leadership
Financial Planning & Analysis
Financial Reporting
Insurance
Investment
Investor Relations
Mergers & Acquisitions
Real Estate
Risk Management
Tax
Treasury
Hospitality & Tourism
Bartender
Chef/Culinary
Event Coordinator
Event Planning
Food Service
Front Desk
Hotel Management
Hotels/Hospitality
Housekeeping
Restaurant Management
Server/Waitstaff
Tour Guide
Travel Agent
Travel/Tourism
Human Resources
Compensation & Benefits
Diversity & Inclusion
Employee Relations
General HR
HR Business Partner
HR Compliance
HR Leadership
HR Operations
Learning & Development
Organizational Development
Payroll
People Analytics
Recruiting/Talent Acquisition
Talent Management
Workforce Planning
Legal
Compliance
Contracts
Corporate Law
Employment Law
General Legal
Intellectual Property
Litigation
Paralegal
Privacy & Data Protection
Regulatory Affairs
Marketing
Advertising
Brand Marketing
Communications
Content Marketing
Demand Generation
Digital Marketing
Email Marketing
Event Marketing
Event Planning
General Marketing
Growth Marketing
Market Research
Marketing Leadership
Marketing Operations
Product Marketing
Public Relations
SEO/SEM
Social Media Marketing
Media & Communications
Audio/Sound
Broadcasting
Content Creator
Copywriting
Editing
Film/Entertainment
Journalism
Public Affairs
Social Media Management
Translation/Writing
Video Production
Medical & Health
Allied Healthcare
Anesthesiology
Cardiology
Dental
Emergency Medicine
Healthcare Clinical
Medical Administration
Medical Research
Nursing
Oncology
Pediatrics
Pharmacy
Physical Therapy
Physicians/Doctors
Psychiatry/Psychology
Radiology
Surgery
Therapy/Mental Health
Veterinary
Non-Profit & Government
Advocacy
Community Outreach
Cultural Institutions
Fundraising
Government Administration
Grant Writing
International Development
Non-Profit/Volunteer
Nonprofit Management
Public Policy
Religious
Social Services
Social Work
Not Employed
Career Break
Freelancer
Job Seeker
Retired
Student
Operations
Business Operations
Distribution
ESG & Sustainability
Facilities Management
Fleet Management
IT Procurement
Inspector/Examiner
Inventory Management
Logistics
Manufacturing/Warehouse
Operations Leadership
Operations/General Mgmt
Process Improvement
Quality Management
Safety/HSE
Supply Chain/Procurement
Vendor Management
Warehouse Management
Personal & Home Services
Beauty
Childcare
Cleaning/Janitorial
Domestic/Care
Eldercare
Fitness/Wellness
Home Repair
Massage Therapy
Personal Assistant
Personal Training
Pet Services
Traditional Crafts
Product
Product Analytics
Product Leadership
Product Management
Product Operations
Product Owner
Product Strategy
Technical Product Management
UX Research
Project & Program Management
Agile/Scrum
Business Analysis
Construction Project Management
IT Project Management
IT/Agile
PMO
Program Management
Public Safety & Security
Corrections
EMT/Paramedic
Firefighter
Inspector/Examiner
Military
Police Officer
Police/Fire/EMT
Private Investigation
Security (Physical)
Security Guard
Research & Science
Clinical Research
Environmental Science
Laboratory
Policy Research
Scientific Research
Social Science
Retail & Consumer
Buying/Merchandising
Cashier
E-commerce Operations
Loss Prevention
Retail Sales
Store Management
Visual Merchandising
Sales
Account Management
Business Development
Channel Sales
Customer Success
Enterprise Sales
Field Sales
General Sales
Inside Sales
Partnership Sales
Real Estate
Revenue Operations
SDR/BDR
Sales Enablement
Sales Engineering
Sales Leadership
Sales Operations
Software
AI/Machine Learning
Backend Engineering
Cloud Engineering
Cloud Operations
Cybersecurity
Data Engineering/Analytics
Database Administration
Database Engineering
DevOps
Embedded Systems
Enterprise Architecture
Firmware Engineering
Frontend Engineering
Fullstack Engineering
IT Infrastructure
IT/Agile
Mobile Engineering
Network Administration
Platform Engineering
QA/Quality
Security Engineering
Site Reliability Engineering
Software Engineering
Solutions Architecture
Systems Administration
Technical Leadership
Technical Writing
UI/UX Design
Video Games
Traditional Engineering
Aerospace Engineering
Architecture
Automotive Engineering
Biomedical Engineering
Chemical Engineering
Civil Engineering
Electrical Engineering
Environmental Engineering
Manufacturing Engineering
Materials Engineering
Mechanical Engineering
Robotics Engineering
Structural Engineering
Technician
Transportation & Logistics
Customs/Import-Export
Delivery Driver
Dispatcher
Freight Forwarding
Maritime
Pilot
Train Operator
Transportation
Truck Driver
```
```
Import & Export
Think Tanks
Environmental Services
Architecture and Planning
Staffing and Recruiting
Legal Services
IT Services and IT Consulting
Insurance
Non-profit Organizations
Venture Capital and Private Equity Principals
Home Health Care Services
Primary and Secondary Education
Software Development
Research Services
Law Practice
Real Estate
Individual and Family Services
Mental Health Care
Real Estate Agents and Brokers
Health and Human Services
Hospitality
Farming
Fundraising
Accounting
Medical Device
Beverage Manufacturing
Wellness and Fitness Services
Hospitals and Health Care
Marketing Services
Financial Services
Outsourcing and Offshoring Consulting
Chemical Manufacturing
Executive Offices
Advertising Services
Transportation, Logistics, Supply Chain and Storage
E-Learning Providers
Travel Arrangements
Education Management
Industry Associations
Information Technology & Services
Writing and Editing
Public Safety
Media Production
Business Consulting and Services
Oil and Gas
Railroad Equipment Manufacturing
Oil, Gas, and Mining
Strategic Management Services
Technology, Information and Internet
Landscaping Services
Wholesale Building Materials
Sporting Goods Manufacturing
Motor Vehicle Manufacturing
Security and Investigations
Civic and Social Organizations
Apparel Manufacturing
Construction
Biotechnology Research
Spectator Sports
Farming, Ranching, Forestry
Housing and Community Development
Veterinary Services
Consumer Services
Utilities
Engineering Services
Professional Training and Coaching
Blogs
Performing Arts
Technology, Information and Media
Human Resources Services
Higher Education
Outsourcing/Offshoring
Wholesale
Building Construction
Industrial Machinery Manufacturing
Government Administration
Newspaper Publishing
Public Policy Offices
Facilities Services
Food and Beverage Services
Automation Machinery Manufacturing
Research
Manufacturing
Health, Wellness & Fitness
Broadcast Media Production and Distribution
Data Infrastructure and Analytics
Retail Furniture and Home Furnishings
Leisure, Travel & Tourism
Medical Practices
Machinery Manufacturing
Retail Apparel and Fashion
Medical Equipment Manufacturing
Musicians
Non-profit Organization Management
Graphic Design
Investment Management
Retail
Computer and Network Security
Repair and Maintenance
Education
Automotive
Translation and Localization
Consumer Goods
Photography
Information Services
Apparel & Fashion
Truck Transportation
Public Relations and Communications Services
Education Administration Programs
Design Services
Pharmaceutical Manufacturing
Wholesale Import and Export
Restaurants
Animation and Post-production
Textile Manufacturing
Transportation/Trucking/Railroad
Freight and Package Transportation
Food & Beverages
Law Enforcement
Shipbuilding
Computers and Electronics Manufacturing
Design
Glass, Ceramics and Concrete Manufacturing
Artists and Writers
Paper and Forest Product Manufacturing
Capital Markets
Mining
Printing Services
Furniture and Home Furnishings Manufacturing
Book and Periodical Publishing
Personal Care Product Manufacturing
Religious Institutions
Business Intelligence Platforms
Market Research
Public Health
International Trade and Development
Appliances, Electrical, and Electronics Manufacturing
Banking
Movies, Videos, and Sound
Renewable Energy Semiconductor Manufacturing
Retail Luxury Goods and Jewelry
Food and Beverage Manufacturing
Telecommunications
Food Production
Mechanical Or Industrial Engineering
Language Schools
Services for Renewable Energy
Human Resources
International Affairs
Sports Teams and Clubs
Ranching
Entertainment Providers
Holding Companies
Retail Art Supplies
Civil Engineering
Interior Design
Political Organizations
Events Services
Chiropractors
Fisheries
Forestry and Logging
Recreational Facilities
Solar Electric Power Generation
Plastics Manufacturing
Internet News
Sports and Recreation Instruction
Tobacco Manufacturing
Wholesale Paper Products
IT System Custom Software Development
Leasing Residential Real Estate
Computer Hardware Manufacturing
Blockchain Services
Online Audio and Video Media
Museums, Historical Sites, and Zoos
Airlines and Aviation
Industrial Automation
Veterinary
Cosmetics
Retail Office Equipment
Leasing Non-residential Real Estate
Entertainment
Wholesale Chemical and Allied Products
Embedded Software Products
Social Networking Platforms
Investment Banking
Equipment Rental Services
Defense and Space Manufacturing
Bars, Taverns, and Nightclubs
Retail Motor Vehicles
Media and Telecommunications
Wholesale Raw Farm Products
Operations Consulting
Sightseeing Transportation
Dairy Product Manufacturing
Renewable Energy Power Generation
Computer Networking Products
Administration of Justice
Janitorial Services
Alternative Medicine
Historical Sites
Building Materials
Warehousing and Storage
Online and Mail Order Retail
Business Content
Music
Maritime Transportation
Professional Organizations
Engines and Power Transmission Equipment Manufacturing
Philanthropic Fundraising Services
Agriculture, Construction, Mining Machinery Manufacturing
Packaging & Containers
Nursing Homes and Residential Care Facilities
Fabricated Metal Products
Retail Groceries
Wood Product Manufacturing
Retail Office Supplies and Gifts
Retail Health and Personal Care Products
Computer Hardware
Dentists
Internet Marketplace Platforms
Furniture
Aviation and Aerospace Component Manufacturing
Motor Vehicle Parts Manufacturing
Semiconductor Manufacturing
Nanotechnology Research
Renewables & Environment
IT System Data Services
Packaging and Containers Manufacturing
Government Relations Services
Insurance Agencies and Brokerages
Computer Games
Paper & Forest Products
E-learning
Community Services
Space Research and Technology
Business Supplies & Equipment
Aviation & Aerospace
Commercial Real Estate
Metalworking Machinery Manufacturing
Food and Beverage Retail
Digital Accessibility Services
Baked Goods Manufacturing
Armed Forces
Wine & Spirits
Pet Services
Specialty Trade Contractors
Wholesale Appliances, Electrical, and Electronics
Physical, Occupational and Speech Therapists
Alternative Dispute Resolution
Consumer Electronics
Arts & Crafts
Wholesale Computer Equipment
Robotics Engineering
Gambling Facilities and Casinos
Community Development and Urban Planning
Measuring and Control Instrument Manufacturing
Personal Care Services
Mobile Food Services
Golf Courses and Country Clubs
Luxury Goods & Jewelry
Biotechnology
Ground Passenger Transportation
Wireless Services
Internet Publishing
Defense & Space
Electrical Equipment Manufacturing
Mobile Computing Software Products
Building Finishing Contractors
Museums
Program Development
Paint, Coating, and Adhesive Manufacturing
Investment Advice
Building Equipment Contractors
Wholesale Luxury Goods and Jewelry
Telephone Call Centers
Boilers, Tanks, and Shipping Container Manufacturing
IT System Design Services
Online Media
Fine Arts Schools
Household Services
Professional Services
Air, Water, and Waste Program Management
Environmental Quality Programs
Commercial and Industrial Machinery Maintenance
Retail Building Materials and Garden Equipment
Architectural and Structural Metal Manufacturing
Desktop Computing Software Products
Primary Metal Manufacturing
Technical and Vocational Training
Glass Product Manufacturing
Electric Power Transmission, Control, and Distribution
Wholesale Metals and Minerals
Wholesale Food and Beverage
Administrative and Support Services
Fire Protection
Security Systems Services
Libraries
Electronic and Precision Equipment Maintenance
Vehicle Repair and Maintenance
Maritime
Semiconductors
Electric Lighting Equipment Manufacturing
Executive Search Services
HVAC and Refrigeration Equipment Manufacturing
Real Estate and Equipment Rental Services
Sound Recording
Animation
Security Guards and Patrol Services
Fine Art
Wholesale Machinery
Dance Companies
Sporting Goods
Waste Collection
Mattress and Blinds Manufacturing
Child Day Care Services
Electric Power Generation
Hospitals
Rail Transportation
Nuclear Electric Power Generation
Residential Building Construction
Women's Handbag Manufacturing
Taxi and Limousine Services
Housing Programs
Breweries
Audio and Video Equipment Manufacturing
Renewable Energy Equipment Manufacturing
Building Structure and Exterior Contractors
Warehousing
Movies and Sound Recording
Meat Products Manufacturing
Wholesale Motor Vehicles and Parts
Sheet Music Publishing
Retail Books and Printed News
Amusement Parks and Arcades
Computer Networking
Public Policy
Hotels and Motels
Data Security Software Products
Retail Appliances, Electrical, and Electronic Equipment
Biomass Electric Power Generation
Laundry and Drycleaning Services
Communications Equipment Manufacturing
Mobile Gaming Apps
Dairy
Subdivision of Land
Water, Waste, Steam, and Air Conditioning Services
Collection Agencies
Accessible Architecture and Design
Animal Feed Manufacturing
Retail Art Dealers
Coal Mining
Conservation Programs
Cosmetology and Barber Schools
Wholesale Alcoholic Beverages
Accommodation and Food Services
Wholesale Drugs and Sundries
Loan Brokers
Vocational Rehabilitation Services
Office Administration
Waste Treatment and Disposal
Agricultural Chemical Manufacturing
Transportation Programs
Book Publishing
IT System Operations and Maintenance
Rubber Products Manufacturing
Periodical Publishing
Trusts and Estates
Accessible Hardware Manufacturing
Horticulture
Footwear Manufacturing
Fashion Accessories Manufacturing
Commercial and Service Industry Machinery Manufacturing
Metal Treatments
Climate Technology Product Manufacturing
Surveying and Mapping Services
Wholesale Hardware, Plumbing, Heating Equipment
Caterers
Outpatient Care Centers
Commercial and Industrial Equipment Rental
Retail Pharmacies
Wholesale Apparel and Sewing Supplies
Philanthropy
Services for the Elderly and Disabled
Robot Manufacturing
Water Supply and Irrigation Systems
Soap and Cleaning Product Manufacturing
Retail Florists
Household and Institutional Furniture Manufacturing
Leather Product Manufacturing
Theater Companies
Office Furniture and Fixtures Manufacturing
Plastics and Rubber Product Manufacturing
IT System Training and Support
Construction Hardware Manufacturing
Military and International Affairs
Sugar and Confectionery Product Manufacturing
Medical and Diagnostic Laboratories
Chemical Raw Materials Manufacturing
Wineries
Legislative Offices
Personal and Laundry Services
Transportation Equipment Manufacturing
Radio and Television Broadcasting
Metal Ore Mining
Public Assistance Programs
Wholesale Recyclable Materials
IT System Installation and Disposal
School and Employee Bus Services
Geothermal Electric Power Generation
Wholesale Footwear
Pipeline Transportation
Wind Electric Power Generation
Wholesale Furniture and Home Furnishings
Spring and Wire Product Manufacturing
Climate Data and Analytics
Government Relations
Insurance Carriers
Tobacco
Funds and Trusts
Reupholstery and Furniture Repair
Fruit and Vegetable Preserves Manufacturing
Physicians
Nonmetallic Mineral Mining
Natural Gas Distribution
Regenerative Design
Highway, Street, and Bridge Construction
Shuttles and Special Needs Transportation Services
Credit Intermediation
Steam and Air-Conditioning Supply
Optometrists
Racetracks
Household Appliance Manufacturing
Emergency and Relief Services
Retail Recyclable Materials & Used Merchandise
Utility System Construction
Temporary Help Services
Urban Transit Services
Funeral Services
Smart Meter Manufacturing
Insurance and Employee Benefit Funds
Utilities Administration
Telecommunications Carriers
Performing Arts and Spectator Sports
Turned Products and Fastener Manufacturing
Seafood Product Manufacturing
Postal Services
Wholesale Petroleum and Petroleum Products
Consumer Goods Rental
Nonresidential Building Construction
Distilleries
Retail Musical Instruments
Zoos and Botanical Gardens
Economic Programs
Skiing Facilities
Metal Valve, Ball, and Roller Manufacturing
Oil Extraction
Bed-and-Breakfasts, Hostels, Homestays
Ambulance Services
Pension Funds
IT System Testing and Evaluation
Courts of Law
Securities and Commodity Exchanges
Correctional Institutions
Claims Adjusting, Actuarial Services
Family Planning Centers
Retail Gasoline
Alternative Fuel Vehicle Manufacturing
Wholesale Photography Equipment and Supplies
Satellite Telecommunications
Cutlery and Handtool Manufacturing
Abrasives and Nonmetallic Minerals Manufacturing
Hydroelectric Power Generation
Ranching and Fisheries
Oil and Coal Product Manufacturing
Flight Training
Interurban and Rural Bus Services
Fossil Fuel Electric Power Generation
Artificial Rubber and Synthetic Fiber Manufacturing
Clay and Refractory Products Manufacturing
Footwear and Leather Goods Repair
Secretarial Schools
Energy Technology
Magnetic and Optical Media Manufacturing
Natural Gas Extraction
Cable and Satellite Programming
Lime and Gypsum Products Manufacturing
Circuses and Magic Shows
Fuel Cell Manufacturing
Savings Institutions
Death Care Services
```
```
Partnership
Nonprofit
Educational
Privately Held
Public Company
Self-Owned
Self-Employed
Government Agency
```
```
Owner
Founder
C-level
Partner
VP
Head
Director
Manager
Senior
```
## **Location Filter**
The location field lets you narrow search results by geographic area. It supports up to four levels of precision, from broad to specific:
1. **Continent** (e.g. North America, Europe)
2. **Country** (in English)
3. **State / Region** (in the country’s local language)
4. **Sub-region** (when applicable, in the country’s local language)
5. **City** (in the country’s local language)
You can use any of these levels. You do not need to provide all of them.
Examples of valid values:
* North America
* United States
* California
* San Francisco
* San Francisco, California, United States
**We strongly recommend trying the filter in the UI first.** It gives you a concrete feel for what values exist and how they are interpreted by the system.
### **How granularity works**
The goal of the location system is to let you “zoom” your search, from very broad to very precise. Each level represents a different zoning depth.
Take two concrete cases:
#### San Francisco (US)
Typical levels:
* Country: United States
* State / Region: California
* City: San Francisco
Here, there is no meaningful sub-region between the state and the city. You move directly from California to San Francisco.
You can therefore search at different depths:
* United States → everything in the US
* California → everything in California
* San Francisco → only San Francisco
Each step narrows the scope.
#### Brest (France)
Typical levels:
* Country: France
* Region: Bretagne
* Sub-region: Finistère
* City: Brest
This adds an extra layer between region and city. You can now search at four different depths:
* France → everything in France
* Bretagne → everything in the Brittany region
* Finistère → everything in that department
* Brest → only the city of Brest
The concept is the same in both cases: each level represents a finer geographic boundary. Some countries have more intermediate layers than others, but the mental model is always “zooming in” on the map.
# Filtering Logic Explained
Source: https://docs.fullenrich.com/api/v2/general/filtering-logic-explained
How the filtering mechanism works
**Combining filters**
If you filter by company industries \["Technology, Information and Internet", "Financial Services"] and company locations \["France", "United States"], the API returns results where the company industry is either Technology, Information and Internet or Financial Services, AND the company location is either France or United States.
In other words, a result must satisfy at least one value in every filter category you specify.
Within a category, values act as OR: a result matches if it fits any of the values. Across categories, the logic is AND: a result must match all categories to be returned.
**Exact match ON vs OFF**
When `exact_match` is set to `false`, the API tolerates minor differences like missing words, extra words, or slight reordering. There is no strict word threshold; instead, the matching scores how closely the input aligns with the stored value and returns results that are reasonably close. For example, "VP of Sales" would match "VP Sales" (missing word) or "VP of Sales and Marketing" (extra words).
When `exact_match` is set to `true`, the value must match exactly as stored (case-insensitive), with no tolerance for variations.
# Getting Started — Search
Source: https://docs.fullenrich.com/api/v2/general/intro-search
Identify the right contacts and companies to engage
Unlike the Enrich API, the Search API is **synchronous**. This means that when you make a search request, the API responds immediately with the matching contacts or companies, based on the filters you provide in the request body.
There are two main endpoints:
* **/people/search** for searching contacts
* **/company/search** for searching companies
Both endpoints accept a wide range of filters (string filters, ranges, exact matches, etc.) so you can build highly targeted searches. Pagination is handled through the offset and limit parameters, which you can use to loop through larger result sets.
All requests require authentication via a Bearer token in the Authorization header. If you haven't set that up yet, check the **Authentication** section first.
Once you're ready, pick the relevant endpoint, define your filters, and send a POST request to start searching.
### Ready to use the API?
To make secure API Calls
Find your first contacts
Find your first companies
How filtering works: AND / OR, exact match, etc..
# API Overview
Source: https://docs.fullenrich.com/api/v2/general/introduction
👋 Welcome to FullEnrich API Documentation
![Hero Light]()
## What is FullEnrich?
We are not just "another data vendor" — we aggregate data from more than 20 providers to achieve the highest enrichment rate in the market.
Get your API key by signing up for FullEnrich for free.
**FullEnrich offers 3 types of APIs:**
1. **Enrich API:** \
Find contact information of people you want to reach out.\
**Data provided:**
* Mobile phone number
* Work email
* Personal email
* Person's professional details (work history, location, education, etc.)
* Company lite details (location, industry, etc.)
2. **Reverse Email Lookup:** \
Identify the person and company behind an email address.\
**Data provided:**
* Full person profile (name, job title, location, work history, etc.)
* Company details (name, industry, headcount, etc.)
3. **Search API:** \
Search for new contacts or companies to reach out to.\
**Data provided:**
* **Contact Search:** Professional details (work history, location, education, etc.) and company lite details (location, industry, etc.)
* **Company Search:** Full company details
*You can also use the Search API to enrich a specific contact or company with the data listed above, without needing a phone number or email.*
Enrich contacts with mobile phone, work email or personal email
Identify the person behind an email
Find contacts & companies by filters
## Native Integrations (no-code)
If you prefer to use FullEnrich in your workflow without writing a line of code, we've got you covered.
**All of them will ask for your FullEnrich API key that** [you can find here](https://app.fullenrich.com/app/api)**.**
Enrich contacts in your Zapier workflow
Enrich contacts in your Make workflow
Enrich contacts natively in Clay using your FullEnrich API key
Enrich contacts in your n8n workflow
## Implementing FullEnrich in your product?
Join dozens of leading B2B platforms; including SalesTech, HRTech, AI agent tools, and other SaaS products, that have integrated FullEnrich directly into their product experience.\
Check out our implementation guide for:
* best practices
* technical insights
* and tips to deliver high-quality enrichment to your users.
# Rate Limit
Source: https://docs.fullenrich.com/api/v2/general/ratelimit
* The API rate limit is **60 API calls per minute**. This applies to all API endpoints: Enrich, Reverse Email Lookup, and Search.
* For Enrich and Reverse Email Lookup, you can send up to **100 contacts in one bulk**, allowing you to process up to **6,000 contacts per minute**.
* Each workspace has a default queue size of **100 concurrent enrichments** and **100 concurrent reverse email lookups**.
* *The Search API is synchronous and does not use a queue.*
***
If you're a technology partner and want to increase your rate limit or the queue size (number of contacts handled in parallel), feel free to reach out to us.
# How Webhooks Work
Source: https://docs.fullenrich.com/api/v2/general/webhooks
The recommended way to receive enrichment results
If you're using **Zapier, Make, Clay, or n8n**, webhooks are handled automatically by these platforms. You can skip this section.
The Enrich API and Reverse Email Lookup are **asynchronous**. This means when you start an operation, the API returns immediately with an ID, and results are delivered later via webhook.
![Async Schema]()
## Why Webhooks?
Webhooks are notifications sent directly to your server when results are ready. Instead of you having to check for results, we push them to you immediately.
**Benefits:**
* **Fastest method** to receive results
* No need to keep a connection open
* No HTTP timeouts or retries to manage
* Simpler and more reliable than polling
## How It Works
1. When you start an enrichment or reverse lookup, include a `webhook_url` in your request
2. We process your contacts (typically 30-90 seconds per contact)
3. When done, we POST the results directly to your webhook URL
The content sent to your webhook is the same as what you'd get from the GET endpoint.
## Webhook Parameters
### `webhook_url` — Batch Completion
Your webhook URL receives a POST request when the **entire batch** is finished, lacks credits, or is canceled.
```json theme={null}
{
"name": "My Enrichment",
"webhook_url": "https://your-server.com/webhook",
"data": [...]
}
```
## Verifying Webhook Authenticity
Every webhook we send is signed so you can confirm it genuinely comes from FullEnrich and wasn't tampered with in transit. We include an `X-Signature-SHA1` header on each request — an HMAC-SHA1 signature of the request body, using your FullEnrich API key as the secret.
To verify a webhook:
1. **Get the signature** — read the `X-Signature-SHA1` value from the request headers.
2. **Read the raw body** — use the raw request body bytes exactly as received (UTF-8). Don't re-serialize the parsed JSON, as key ordering or whitespace changes will break the check.
3. **Compute the HMAC** — create an HMAC-SHA1 hash of the body using your API key as the secret, and hex-encode the result (lowercase).
4. **Compare** — if your computed hash matches the `X-Signature-SHA1` header, the request is authentic. Use a constant-time comparison to avoid timing attacks.
Verify the signature against the **raw request body**, before any JSON parsing or reformatting. Signing a re-serialized payload will produce a different hash and fail the check.
```javascript Node.js theme={null}
import crypto from "crypto";
// Use the raw request body (e.g. via express.raw({ type: "application/json" }))
function isValidWebhook(rawBody, signatureHeader, apiKey) {
const expected = crypto
.createHmac("sha1", apiKey)
.update(rawBody, "utf8")
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signatureHeader)
);
}
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.header("X-Signature-SHA1");
if (!isValidWebhook(req.body, signature, process.env.FULLENRICH_API_KEY)) {
return res.status(401).send("Invalid signature");
}
const payload = JSON.parse(req.body);
// ... handle the verified payload
res.sendStatus(200);
});
```
```python Python theme={null}
import hashlib
import hmac
def is_valid_webhook(raw_body: bytes, signature_header: str, api_key: str) -> bool:
expected = hmac.new(
api_key.encode("utf-8"),
raw_body,
hashlib.sha1,
).hexdigest()
return hmac.compare_digest(expected, signature_header)
# Flask example
@app.route("/webhook", methods=["POST"])
def webhook():
signature = request.headers.get("X-Signature-SHA1", "")
if not is_valid_webhook(request.get_data(), signature, API_KEY):
return "Invalid signature", 401
payload = request.get_json()
# ... handle the verified payload
return "", 200
```
```php PHP theme={null}
## Reliability & Retries
Webhooks are reliable by design. If we can't deliver your result (for example, receiving a non-2xx status code), we'll automatically **retry every minute, up to 5 times**.
For most use cases, you can treat webhooks as "guaranteed delivery." If there's ever a question about a specific result or missed event, our team can check our delivery logs on request.
## Tracking Requests with `custom`
You can easily keep track of which result belongs to which user or request by using the `custom` parameter. Include any identifier you need (User ID, CRM contact ID, etc.), and it will be returned exactly as provided in the webhook payload.
```json theme={null}
{
"data": [
{
"first_name": "John",
"last_name": "Doe",
"domain": "example.com",
"custom": {
"user_id": "12584",
"crm_contact_id": "abc-123"
}
}
]
}
```
Custom field values must be strings. Numbers will return an error.
## Testing Webhooks
A quick way to test webhooks and see the payload structure is to use [**webhook.site**](https://webhook.site) — a free service that gives you a temporary URL to receive and inspect webhook requests.
## Polling (Not Recommended)
Polling means repeatedly calling the GET endpoint to check if the operation is finished. This is **not recommended** because:
* It consumes your rate limit quota
* Results come slower than with webhooks
* More complex to implement reliably
If you must use polling, don't poll more than once every 5-10 minutes. Never poll every few seconds.
## Real-Time Webhook Events
### `webhook_events.contact_finished`
If you need results as fast as possible, use this parameter. It fires a webhook **immediately after each individual contact** is enriched, without waiting for the entire batch to complete.
This is perfect for real-time integrations where you want to process results as they come in.
```json theme={null}
{
"name": "My Enrichment",
"webhook_url": "https://your-server.com/webhook/batch-complete",
"webhook_events": {
"contact_finished": "https://your-server.com/webhook/single-contact"
},
"data": [...]
}
```
You can use both `webhook_url` and `webhook_events.contact_finished` together. You'll receive a webhook for each contact as it completes, plus a final webhook when the entire batch is done.
### Event Payload
The webhook receives the enriched profile immediately after processing. The payload follows the standard response format with a single contact in the `data` array:
```json theme={null}
{
"id": "",
"name": "",
"status": "IN_PROGRESS",
"cost": {
"credits": 10
},
"data": [
{
"input": {
"first_name": "",
"last_name": "",
"full_name": "",
"company_domain": "",
"company_name": "",
"professional_network_url": ""
},
"custom": {},
"contact_info": {
"most_probable_work_email": {
"email": "",
"status": "DELIVERABLE"
},
"most_probable_personal_email": {
"email": "",
"status": "DELIVERABLE"
},
"most_probable_phone": {
"number": "",
"region": ""
},
"work_emails": [
{
"email": "",
"status": "DELIVERABLE"
}
],
"personal_emails": [
{
"email": "",
"status": "DELIVERABLE"
}
],
"phones": [
{
"number": "",
"region": ""
}
]
},
"profile": {
"id": "",
"full_name": "",
"first_name": "",
"last_name": "",
"headline": "",
"description": "",
"location": {
"country": "",
"country_code": "",
"city": "",
"region": ""
},
"social_profiles": { ... },
"educations": [{ ... }],
"languages": [{ ... }],
"skills": [""],
"employment": { ... }
}
}
]
}
```
The `status` will be `IN_PROGRESS` since individual contacts are sent as they complete, before the entire batch finishes.
# Getting Started & Concepts
Source: https://docs.fullenrich.com/api/v2/implement-in-product/getting-started
Our API is also built for companies that want to integrate FullEnrich directly into their own product. If that's your goal, you're in the right place.
## Introduction
FullEnrich is designed to help you enrich contacts, identify people from emails, and search for contacts & companies at scale, using data from more than 20 providers with a strong focus on quality and coverage.
**FullEnrich offers 3 types of APIs:**
* **Enrich API** (asynchronous) — Find emails and phone numbers for B2B contacts
* **Reverse Email Lookup** (asynchronous) — Identify the person and company behind an email address
* **Search API** (synchronous) — Search for contacts and companies based on filters
The Enrich and Reverse Email Lookup APIs are asynchronous: you send requests and receive results via webhooks as soon as they're ready. The Search API is synchronous and returns results immediately.
### API Endpoint Reference
All technical details, request/response payloads, and code snippets are available in our API documentation.
Always refer to the main documentation for up-to-date specs.
## Asynchronous Model & Result Retrieval
*This section applies to the Enrich API and Reverse Email Lookup. The Search API is synchronous and returns results immediately.*
All enrichment and reverse lookup requests are asynchronous. You send the request, and results are available as soon as they're ready. Most operations take between 30 and 90 seconds, depending on provider response time.
**2 Ways to Get Your Results:**
### **1. Webhooks (Recommended - Fastest Method)**
Webhooks are notifications sent directly to your server when results are ready. Instead of you having to check for results, we push them to you immediately (fastest way to get enrichment results).
FullEnrich is designed for asynchronous usage, and webhooks are the only recommended way to receive enrichment results. When your enrichment is done, we POST the result directly to the webhook URL you provide. This means you don't have to keep a connection open or handle HTTP timeouts, retries, or connection errors. For most product teams, this is both simpler, faster, and much more reliable than managing long-running requests yourself.
Webhooks are reliable by design. If, for any reason, we can't deliver your result (for example, a network issue on your server), we'll automatically retry delivery 5 times. For most use cases, you can treat webhooks as "guaranteed delivery." If there's ever a question about a specific result or missed event, our team can check our delivery logs on request.
**Easy webhook implementation:** You can easily keep track of which enrichment belongs to which user or request by using the `custom` parameter when creating an enrichment. For example, you can include a User ID, Enrichment ID, or any other value that helps you match the result to your internal data. This value will be sent back to you exactly as provided, inside the `custom` object in the webhook payload.
Example usage:
```json theme={null}
"custom": {
"user_id": "12584"
}
```
A quick way to check the result payload and troubleshoot is to use a webhook URL from [webhook.site](http://webhook.site).
### **2. Polling (Not Recommended)**
Polling means repeatedly checking an endpoint to see if the enrichment is finished. This method requires you to actively check for results at regular intervals.
Polling is not encouraged because it will consume your rate limit quota without benefit. If you have to implement polling, we recommend not polling more than once every 5–10 minutes. Never poll every few seconds.
***
### **Queue Retention**
There's no limit on the number of queued contacts or how long they can stay in the queue. Once a contact is queued for enrichment, it remains there until it's processed. Jobs don't expire and there's no automatic timeout. If a provider in our waterfall is down, the system will automatically skip it and move on to the next one, ensuring very high uptime: [**https://status.fullenrich.com/**](https://status.fullenrich.com/)
# Deploying in Production
Source: https://docs.fullenrich.com/api/v2/implement-in-product/production
### Handling invalid input data
When using the bulk enrichment endpoint (`/api/v2/contact/enrich/bulk`), you can add the `silentFail` query parameter:
```
/api/v2/contact/enrich/bulk?silentFail=true
```
With this parameter, if a contact in your batch has invalid or missing data (LinkedIn URL, domain, name, etc.), that contact will simply be skipped during enrichment. The rest of the batch will be processed as usual.
This prevents a single invalid contact from blocking the enrichment of your entire batch. FullEnrich will handle these cases automatically and silently skip problematic contacts.
### Setting Up Low-Credit Alerts
You can set up a low credit alert directly from your FullEnrich dashboard to avoid running out of credits and blocking new operations.
It's in the settings of the webapp:
We recommend enabling this alert for production use to stay notified before your credits run out and keep your enrichment workflow running smoothly.
# Quality Over Speed
Source: https://docs.fullenrich.com/api/v2/implement-in-product/quality-over-speed
**A quick clarification before we dive in.**
When we talk about enrichment speed here, we're referring to the time it takes to enrich a *single contact*, not to overall throughput or scale. FullEnrich is built to handle volume. Some of our customers enrich millions of contacts every month with us.
When you integrate FullEnrich's API, you'll notice enrichment takes around 45-60 seconds per contact. If you've tried other providers in the past and it took 5-15 seconds to get a result, this might feel long. So let's talk about what's actually happening during that time, and what you'd be giving up if we made it faster.
## The reality of B2B data enrichment
We reject over 30% of the data our providers return to us. The numbers are invalid, the emails bounce, the data simply doesn't pass our checks.
When you request a phone number, we're not just pulling it from a database and handing it to you. We're running a gauntlet of validations:
1. We query a provider and find a number
2. We check if the number is even valid (proper format, real carrier)
3. We verify if it's currently in service
4. We verify if it's a mobile phone (we exclude landlines)
5. We confirm the line actually belongs to your prospect, not their old company or a recycled number
If you want to take a deeper look at how we verify emails and phone numbers, check out the articles below.
When any of these checks fail, we start over with another provider. Then another. Sometimes we go through 5, 10, 15 sources before we find a number that passes every validation, or before we're confident enough to tell you there isn't one.
## What are the alternatives?
We could have built just another data provider. One that responds in 10 seconds. Here's what that would look like:
These providers work from large static databases. That phone number has been sitting there for 3 years. The query is fast precisely because there's no real work happening; just a simple database lookup.
The result? Lower coverage (because they only have what's in their database), uncertain quality (because data decays constantly), and ultimately, wasted time chasing dead numbers or wrong people.
That's not us. And it never will be.
The whole reason we built FullEnrich is because the status quo wasn't good enough. Most data providers deliver mediocre quality, and teams just accepted it as normal. We didn't want to be another one of those. The quality and coverage we're able to deliver today is a direct result of the process that takes that extra time.
## Why the best providers are the slowest
This is counterintuitive, but the providers with the highest quality data are often the slowest. They're doing real-time lookups, hitting live sources, running their own validations. A single provider might take 30 seconds to respond.
Now multiply that by the 15-20 providers we query in a waterfall. Even at 5 seconds each, that adds up. And some of those slow providers are irreplaceable; they have coverage no one else can match.
## We asked ourselves this question on day one
When we built FullEnrich, we had to decide: do we optimize for speed, or do we optimize for quality?
We chose quality.
Not because fast isn't appealing, but because we've seen what happens when enrichment prioritizes speed. Your CRM fills up with bad numbers. Your team burns hours on dead leads. Your deliverability tanks. The time you "saved" on enrichment costs you 10x in wasted effort downstream.
That said, our engineering team is constantly working to reduce enrichment time. We optimize provider selection, parallelize where we can, and we're willing to make trade-offs when they make sense. If an extra check would give us 0.2% more accuracy but add 30 seconds, we wouldn't implement it. But we'll never sacrifice the core validations that make our data reliable.
## How to communicate this to your users
Most enrichments complete within 30 to 90 seconds per contact (average is 56s). What matters most is the value users get from the enrichment. If your product communicates that you're sourcing data from many premium providers to guarantee the most complete and up-to-date information, users naturally accept the wait. The more transparent you are about the process, the more the waiting time feels justified.
**Best practices for integrating enrichment in your product:**
* **Don't block users during enrichment.** Let them continue their workflow while the enrichment runs in the background.
* **Display a clear status in the UI** so users know the process is ongoing.
* **Rotate between dynamic loading messages** to make the experience smoother:
* "Enrichment in progress…"
* "Searching across 20 data providers…"
* "Checking every corner…"
* "Digging deeper…"
The wait feels proportional to the value delivered. Good communication turns patience into a signal of thoroughness.
# Rate Limits & Volume
Source: https://docs.fullenrich.com/api/v2/implement-in-product/volume
### Rate Limit
The default rate limit is **60 requests per minute**. This applies to all API calls: Enrich, Reverse Email Lookup, and Search.
For Enrich and Reverse Email Lookup, you can send up to 100 contacts per request, allowing you to process up to 6,000 contacts per minute.
**Are you currently hitting the rate limit?**\
Make sure you’ve implemented webhooks properly, since polling also consumes rate limits. If you’re still hitting the limit, reach out to our team, and we can increase it if needed.
Our API uses a fixed window rate limiter. Each calendar minute has its own request counter: by default, you can make up to 60 requests per minute. The counter resets at the start of every new minute. This means you can use your full quota in a single burst, but once the limit is reached, further requests will be rejected until the next minute begins.
### Queue Size
Each workspace has a default queue size of:
* **100 concurrent enrichments** (Enrich API)
* **100 concurrent reverse email lookups** (Reverse Email Lookup API)
If you submit more contacts than your queue can handle, the extra contacts wait in the queue until a slot is free. As soon as a running operation finishes, the next one in the queue starts.
*The Search API is synchronous and does not use a queue.*
**Dedicated Workspaces for Different Workloads**
If your application mixes batch processing and real-time enrichment, we can isolate these flows into two separate workspaces. Each workspace runs on an independent queue, keeping your real-time calls fast even when your batch jobs ramp up.
**Need a higher queue size?**\
Queue size can be increased for high-volume customers and is set based on your volume in the commercial agreement. Reach out to our team to discuss.
### Real-Time Enrichment
If you need results as fast as possible (closest to real-time), use the `webhook_events.contact_finished` parameter when starting an enrichment. This webhook fires immediately after each individual contact is enriched, without waiting for the entire batch to complete.
This means you don't need to send one contact per request to get fast results — you can still batch multiple contacts together and receive a webhook for each one as soon as it's ready.
# Look Up People
Source: https://docs.fullenrich.com/api/v2/people/lookup/post
api/v2/reference/openapi.yml POST /people/lookup
Look up a single person using their identifiers (professional network URL/ID, or full name combined with a company identifier). Returns the best matching person.
The People Look Up endpoint returns a single person when you already know who you are looking for. Provide an identifier and the API matches the best corresponding profile.
The most reliable way to match a person is their **professional network URL or ID**. You can also look up by **full name combined with a company identifier** (domain, professional network URL, or professional network ID) to disambiguate the match.
The response has the same shape as [Search People](/api/v2/people/search/post), but always contains at most one person.
[Search API pricing](/api/v2/general/credit)
# Search People
Source: https://docs.fullenrich.com/api/v2/people/search/post
api/v2/reference/openapi.yml POST /people/search
Search for people based on various filters. Multiple filters within the same field are combined with AND logic.
The People Search endpoint lets you build precise **lists of individuals based** on role, seniority, skills, location, company attributes, and career history. You can combine multiple filters to narrow down exactly the profiles you are looking for, whether you are targeting new hires, decision-makers, or specific personas.
**How filters work (AND / OR)**
If you filter by job titles \["CEO", "CTO", "VP Sales"] and locations \["France", "United States"], the API returns results where the job title is any of CEO, CTO, or VP Sales, AND the location is either France or United States.
In other words, a result must satisfy at least one value in every filter category you specify.
Within a category, values act as OR: a result matches if it fits any of the values. Across categories, the logic is AND: a result must match all categories to be returned.
Once you're ready, pick the relevant endpoint, define your filters, and send a POST request to start searching.
**If you already know exactly who you want to retrieve**, you can also search for a specific person using their professional network URL, which is the most reliable way to match a single individual.
[Search API pricing](/api/v2/general/credit)
For a full list of supported filters and accepted values (industries, company types, seniority levels, etc.)
For a full list of supported filters and accepted values (industries, company types, seniority levels, etc.)