> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fullenrich.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Start Bulk Enrichment
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.
## OpenAPI
````yaml api/v2/reference/openapi.yml POST /contact/enrich/bulk
openapi: 3.1.0
info:
title: FullEnrich API Documentation
version: 2.0.0
description: >
FullEnrich API enables you to enrich B2B contacts with emails and phone
numbers using data from 20+ providers.
We are GDPR and CCPA compliant.
servers:
- url: https://app.fullenrich.com/api/v2
security: []
paths:
/contact/enrich/bulk:
post:
summary: Enrich Contacts In Bulk
operationId: postContactBulkEnrich
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RequestPostContactBulkEnrich'
example:
name: Sales Operations in London
webhook_url: https://example.com/webhook
webhook_events:
contact_finished: https://example.com/webhook/contact
data:
- first_name: John
last_name: Snow
domain: example.com
company_name: Example Inc
linkedin_url: https://www.linkedin.com/in/demoge/
enrich_fields:
- contact.work_emails
- contact.personal_emails
- contact.phones
custom:
user_id: '12584'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ResponsePostContactBulkEnrich'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
EnrichmentNameNotSet:
value:
code: error.enrichment.name.empty
message: Enrichment name not set
WebhookURLInvalid:
value:
code: error.enrichment.webhook_url
message: Webhook URL must be start with http or https
ProviderNotSet:
value:
code: error.enrichment.provider.empty
message: Providers not set
DataNotSet:
value:
code: error.enrichment.data.empty
message: Data is empty
FirstNameNotSet:
value:
code: error.enrichment.first_name.empty
message: First name cannot be empty
LastNameNotSet:
value:
code: error.enrichment.last_name.empty
message: Last name cannot be empty
DomainNotSet:
value:
code: error.enrichment.domain.empty
message: Domain cannot be empty
EnrichFieldsNotSet:
value:
code: error.enrichment.enrich_fields.empty
message: enrichFields cannot be empty
EnrichFieldValue:
value:
code: error.enrichment.enrich_field.value
message: >-
enrichField 'xxxx' not valid must be contact.work_emails
or contact.phones or contact.personal_emails
CustomKeyExceeded:
value:
code: error.enrichment.custom.key.exceeded
message: 'Custom field contains too many keys (max: 10 keys)'
CustomKeyValueExceeded:
value:
code: error.enrichment.custom.value.exceeded
message: 'Custom field value max len exceeded (max: 100 character)'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
AuthorizationHeaderNotSet:
value:
code: error.authorization.not_set
message: Authorization headers not set
AuthorizationHeaderNotAnBearer:
value:
code: error.authorization.not_bearer
message: Authorization headers do not have prefix 'bearer'
UnknownApiKey:
value:
code: error.api.key
message: Unknown api key
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
RateLimitExceeded:
value:
code: error.rate.limit
message: Too many requests. Try again in 1m
security:
- BearerAuth: []
components:
schemas:
RequestPostContactBulkEnrich:
type: object
example:
name: Sales Operations in London
webhook_url: https://example.com/webhook
webhook_events:
contact_finished: https://example.com/webhook/contact
data:
- first_name: John
last_name: Snow
domain: example.com
company_name: Example Inc
professional_network_url: https://www.linkedin.com/in/demoge/
enrich_fields:
- contact.work_emails
- contact.personal_emails
- contact.phones
custom:
user_id: '12584'
properties:
name:
type: string
description: A readable name for this enrichment (visible in your dashboard)
webhook_url:
type: string
description: >-
URL that will receive a POST request when the entire enrichment is
finished (all contacts processed).
webhook_events:
type: object
description: Optional webhook URLs for specific events during enrichment
properties:
contact_finished:
type: string
description: >-
URL that receives a POST request each time a single contact is
enriched, without waiting for the entire batch to complete.
Useful for real-time updates.
data:
type: array
items:
$ref: '#/components/schemas/RequestPostContactBulkEnrichContact'
required:
- name
- providers
- data
ResponsePostContactBulkEnrich:
type: object
properties:
enrichment_id:
type: string
format: uuid
examples:
- 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
Error:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
- message
RequestPostContactBulkEnrichContact:
type: object
properties:
first_name:
type: string
last_name:
type: string
domain:
type: string
company_name:
type: string
linkedin_url:
type: string
description: >-
Supports standard LinkedIn profile URLs (e.g.,
https://www.linkedin.com/in/demoge) as well as LinkedIn Sales
Navigator URLs (e.g.,
https://www.linkedin.com/in/ACwAACLLwaIBKi655883b).
enrich_fields:
type: array
items:
type: string
enum:
- contact.work_emails
- contact.phones
- contact.personal_emails
custom:
type: object
description: >-
Returned in the enrichment result. Use it to identify a user, a CRM
contact, or to pass any other information. All values must be
strings. Limited to 20 entries.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: string
````