> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lemlist.com/llms.txt
> Use this file to discover all available pages before exploring further.
> Performs batch enrichment for up to 500 entities to find emails, phone numbers, or LinkedIn data.
# Bulk Enrich Data
Unlike other endpoints, this one starts with `/v2/enrichments`.
## How to use the endpoint
The bulk enrichment API is ideal for:
* Processing large lists of prospects efficiently
* Enriching CRM data in batches
* Finding and verifying multiple contacts simultaneously
* Automating data enrichment workflows at scale
### Enrichment Types
| Type | Required Input | Description |
| --------------------- | ------------------------------------------------------------------------------------------- | --------------------------------- |
| `find_email` | `linkedinUrl` OR (`firstName` + `lastName` + `companyName` + `companyDomain`) | Find and verify email addresses |
| `find_phone` | `linkedinUrl` | Find phone numbers |
| `verify` | `email` | Verify email deliverability |
| `linkedin_enrichment` | `linkedinUrl` OR `email` OR (`firstName` + `lastName` + (`companyName` OR `companyDomain`)) | Enrich with LinkedIn profile data |
### Metadata
The `metadata` field can be a string or an object. This data will be returned in both the API response and webhook notifications, allowing you to track and correlate enrichment requests.
## Response
The API returns an array where each element corresponds to a request in the input array. Successful requests return an enrichment ID, while failed requests return an error code.
```json success theme={"theme":"dracula"}
{
"id": "enr_cawQhM9N3pWkqw2Yt",
"metadata": {
"some_id": "some_id"
}
}
```
```json error theme={"theme":"dracula"}
{
"error": "MISSING_INPUTS",
"metadata": "some_id"
}
```
## Getting Results
Check [Enrich Data](/api-reference/endpoints/enrich/enrich-data) for details on the enrichment result structure.
Since enrichment is asynchronous, you can retrieve results in two ways:
1. **Polling**: Use the [Get Enrichment Result](/api-reference/endpoints/enrich/get-enrichment-result) endpoint with the returned enrichment ID
2. **Webhooks**: Provide a `webhookUrl` query parameter to receive notifications when enrichments complete
Learn more about webhooks in the [Enrich object definition](/api-reference/objects-definitions/enrich#webhooks).
## Error Codes
| Error Code | Description |
| --------------------------------- | ------------------------------------------------------------------- |
| `WRONG_INPUT_FORMAT` | The input must be an object containing at least one valid field |
| `WRONG_METADATA_FORMAT` | The metadata field must be a string or an object |
| `NO_WORKFLOW_REQUESTED` | At least one enrichment type must be specified |
| `WRONG_ENRICHMENT_REQUEST_FORMAT` | The enrichmentRequests field must be an array |
| `UNAUTHORIZED_WORKFLOW_REQUESTED` | Invalid enrichment type specified |
| `TOO_MANY_ENRICHMENTS_REQUESTED` | Maximum 500 enrichments per request |
| `NO_ENRICHMENTS_REQUESTED` | The body must contain at least one enrichment |
| `WRONG_BODY_FORMAT` | The body must be a valid JSON array |
| `MISSING_INPUTS` | Required input fields are missing for the requested enrichment type |
| `MISSING_EMAIL` | Email is required for verify enrichment |
| `MISSING_LINKEDIN_URL` | LinkedIn URL is required for this enrichment type |
## Limits
* **Maximum requests per call**: 500 enrichments
* **Rate limits**: Standard API rate limits apply (20 requests per 2 seconds)
* **Credits**: Each enrichment type consumes credits from your team's balance
See [lemlist API credits](/api-reference/objects-definitions/credits) for more information about credit consumption.
## OpenAPI
````yaml post /v2/enrichments/bulk
openapi: 3.0.0
info:
title: lemlist API
version: 1.0.0
description: >-
Welcome to the lemlist Developer Documentation.
lemlist is very customizable and open. You'll find on this page all the API
and integration you can do with lemlist.
# Rate Limit
lemlist's API rate limits requests in order to prevent abuse and overload of
our services.
Rate limits are applied on all routes and per API key performing the
request.
The rate limits are **20** requests per **2** seconds.
The response provides any information you may need about it:
| Header | Description |
| --- | --- |
| Retry-After | The number of seconds in which you can retry |
| X-RateLimit-Limit | The maximum requests in that time |
| X-RateLimit-Remaining | The number of remaining requests you can make |
| X-RateLimit-Reset | The date when the rate limit will reset |
_Example of values for the rate limit headers_
``` json
{
"Retry-After": 2,
"X-RateLimit-Limit": 20,
"X-RateLimit-Remaining": 7,
"X-RateLimit-Reset" : "Tue Feb 16 2021 09:02:42 GMT+0100 (Central European Standard Time)"
}
```
# Definitions
## Team
A team is the entity of lemlist that can handle users and billing.
## Credits
Credits are the coins a team uses to enrich emails, LinkedIn URLs, etc. via
the enrich route. Each enrichment feature needs a certain amount of credits
to run.
## User
You use a user account to connect to lemlist and send messages via the
connected emails or LinkedIn account.
## Campaign
A campaign is the entity to automate outreach. A campaign has multiple
sequences composed of steps.
## Lead
A lead is a person that you try to contact via a campaign.
## Activity
An activity is the history of all the steps.
## Unsubscribe
An unsubscribe occurs when a person decides they don't want to receive
emails from you anymore.
# Authentication
All API routes use the dedicated subdomain `api.lemlist.com`.
lemlist uses API keys to allow access to the API. You can get your lemlist
API key at our [integration
page](https://app.lemlist.com/settings/integrations).
You need to add the `Authorization` header using the `Basic` authentication
type. `login:password` **where the login is always empty and the password is
the API key**.
⚠️ **Don't forget to add the semicolon (**`:`**) before your API key in curl
command.**
> To authorize, use this code:
``` shell
curl https://api.lemlist.com/api/team \
--user ":YourApiKey"
```
**Make sure to replace** **`YourApiKey`** **with your API key.**
# Give feedback
If you want to report a bug, ask for data, or share with us a use case,
please fill this [form](https://lemlist.typeform.com/to/mfVlkyGf). It will
help us centralize your needs!
servers:
- url: https://api.lemlist.com/api
security:
- basicAuth: []
paths:
/v2/enrichments/bulk:
post:
tags:
- Enrich
summary: Bulk Enrich Data
description: >-
Send a batch of enrichment requests for multiple entities. Maximum 500
enrichment requests per call.
parameters:
- name: webhookUrl
in: query
required: false
description: Webhook URL for enrichment events
example: https://n8n.example.com/webhook/lemlist-webhook-surprise
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: array
maxItems: 500
items:
type: object
required:
- enrichmentRequests
properties:
input:
type: object
description: >-
Input data for enrichment. Required fields depend on
enrichmentRequests.
properties:
linkedinUrl:
type: string
description: The LinkedIn URL of the person
example: https://www.linkedin.com/in/john-doe
email:
type: string
description: The email of the person
example: john.doe@example.com
companyName:
type: string
description: The name of the company associated with the person
example: Example Company
companyDomain:
type: string
description: >-
The domain of the company associated with the person.
Recommended for better find rate
example: example.com
firstName:
type: string
description: The first name of the person
example: John
lastName:
type: string
description: The last name of the person
example: Doe
jobTitle:
type: string
description: >-
The job title of the person. Optional hint that
improves the find rate when matching the right person.
example: Marketing Manager
enrichmentRequests:
type: array
description: >-
Array of enrichment types to perform. Must contain at
least one of: find_email, find_phone, verify,
linkedin_enrichment
items:
type: string
enum:
- find_email
- find_phone
- verify
- linkedin_enrichment
example:
- find_email
- verify
metadata:
description: >-
Custom data to be returned in the response and webhook.
Can be a string or an object
oneOf:
- type: string
- type: object
example:
id: some_id
examples:
find_email:
summary: Find email enrichment
value:
- input:
companyName: Example Ets
companyDomain: example.com
firstName: John
lastName: Doe
enrichmentRequests:
- find_email
metadata:
id: some_id
- input:
linkedinUrl: https://www.linkedin.com/in/john-doe
enrichmentRequests:
- find_email
metadata: some_id
find_phone:
summary: Find phone enrichment
value:
- input:
linkedinUrl: https://www.linkedin.com/in/john-doe
enrichmentRequests:
- find_phone
metadata:
id: some_id
verify:
summary: Verify email
value:
- input:
email: john.doe@example.com
enrichmentRequests:
- verify
metadata:
id: some_id
linkedin_enrichment:
summary: LinkedIn enrichment
value:
- input:
linkedinUrl: https://www.linkedin.com/in/john-doe
enrichmentRequests:
- linkedin_enrichment
metadata:
id: some_id
multiple:
summary: Multiple enrichments
value:
- input:
linkedinUrl: https://www.linkedin.com/in/john-doe
email: john.doe@example.com
companyName: Example Company
companyDomain: example.com
firstName: John
lastName: Doe
jobTitle: Marketing Manager
enrichmentRequests:
- find_email
- find_phone
- verify
- linkedin_enrichment
metadata:
some_id: some_id
responses:
'200':
description: Success - Returns enrichment IDs and metadata for each request
content:
application/json:
schema:
type: array
items:
oneOf:
- type: object
properties:
id:
type: string
description: Enrichment ID
example: enr_KzCb0f9dbIjtRqyEO
metadata:
description: The metadata provided in the request
oneOf:
- type: string
- type: object
- type: object
properties:
error:
type: string
description: Error code for failed enrichment
example: MISSING_INPUTS
metadata:
description: The metadata provided in the request
oneOf:
- type: string
- type: object
examples:
find_email:
summary: Find email response
value:
- id: enr_rt3yG1uvSOAmNgsOm
metadata:
id: some_id
- id: enr_KdG7p3VNyiCgmcYTv
metadata: some_id
- error: MISSING_INPUTS
metadata: some_id
find_phone:
summary: Find phone response
value:
- id: enr_bPawymIrM37F6yHBe
metadata:
id: some_id
- error: MISSING_INPUTS
metadata: some_id
verify:
summary: Verify email response
value:
- id: enr_N84uOiUB0RYx5LIEb
metadata:
id: some_id
- error: MISSING_EMAIL
metadata: some_id
linkedin_enrichment:
summary: LinkedIn enrichment response
value:
- id: enr_zsHo0j5j6HNC0MXgQ
metadata:
id: some_id
- error: MISSING_LINKEDIN_URL
metadata: some_id
'400':
description: Bad Request - Invalid input format or parameters
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- WRONG_INPUT_FORMAT
- WRONG_METADATA_FORMAT
- NO_WORKFLOW_REQUESTED
- WRONG_ENRICHMENT_REQUEST_FORMAT
- UNAUTHORIZED_WORKFLOW_REQUESTED
- TOO_MANY_ENRICHMENTS_REQUESTED
- NO_ENRICHMENTS_REQUESTED
- WRONG_BODY_FORMAT
examples:
wrong_input_format:
summary: Wrong input format
description: >-
The input of each enrichment must be an object containing at
least one of the required fields
value:
error: WRONG_INPUT_FORMAT
wrong_metadata_format:
summary: Wrong metadata format
description: The metadata field must be a string or an object
value:
error: WRONG_METADATA_FORMAT
no_workflow_requested:
summary: No workflow requested
description: >-
The enrichment request must contain at least one of the
authorized workflows (find_email, find_phone, verify,
linkedin_enrichment)
value:
error: NO_WORKFLOW_REQUESTED
wrong_enrichment_request_format:
summary: Wrong enrichment request format
description: The enrichment request must be an array
value:
error: WRONG_ENRICHMENT_REQUEST_FORMAT
unauthorized_workflow_requested:
summary: Unauthorized workflow requested
description: The enrichmentRequests contained invalid request types
value:
error: UNAUTHORIZED_WORKFLOW_REQUESTED
too_many_enrichments_requested:
summary: Too many enrichments requested
description: There is a limit of 500 enrichments per request
value:
error: TOO_MANY_ENRICHMENTS_REQUESTED
no_enrichments_requested:
summary: No enrichments requested
description: The body must contain at least one enrichment request
value:
error: NO_ENRICHMENTS_REQUESTED
wrong_body_format:
summary: Wrong body format
description: The body must be a valid array
value:
error: WRONG_BODY_FORMAT
'401':
description: Unauthorized - The authentication you supplied is incorrect
content:
text/plain:
example: The authentication you supplied is incorrect
'405':
description: Method not allowed
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
````