curl --request POST \
--url https://api.lemlist.com/api/v2/enrichments/bulk \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
[
{
"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"
}
]
'
[
{
"id": "enr_ExampleA1b2C3d4E5",
"metadata": {
"id": "some_id"
}
},
{
"id": "enr_ExampleF6g7H8i9J0",
"metadata": "some_id"
},
{
"error": "MISSING_INPUTS",
"message": "Missing LinkedIn url OR the combination of first name, last name, company name, company domain",
"metadata": "some_id"
}
]
Enrich
Bulk Enrich Data
Performs batch enrichment for up to 500 entities to find emails, phone numbers, or LinkedIn data.
POST
/
v2
/
enrichments
/
bulk
curl --request POST \
--url https://api.lemlist.com/api/v2/enrichments/bulk \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
[
{
"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"
}
]
'
[
{
"id": "enr_ExampleA1b2C3d4E5",
"metadata": {
"id": "some_id"
}
},
{
"id": "enr_ExampleF6g7H8i9J0",
"metadata": "some_id"
},
{
"error": "MISSING_INPUTS",
"message": "Missing LinkedIn url OR the combination of first name, last name, company name, company domain",
"metadata": "some_id"
}
]
Unlike other endpoints, this one starts with
/v2/enrichments.Every call starts new enrichments and uses credits, even when the same person was enriched before.
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
Required inputs
| Type | Required input | Description |
|---|---|---|
find_email | linkedinUrl OR (firstName + lastName + (companyName OR companyDomain)) OR email | Find the person’s email and check its deliverability |
find_phone | linkedinUrl OR (firstName + lastName + (companyName OR companyDomain)) OR email | Find phone numbers |
verify | a valid email | Verify email deliverability |
linkedin_enrichment | linkedinUrl OR email OR (firstName + lastName + (companyName OR companyDomain)) | Enrich with LinkedIn profile data |
linkedinUrlmust be a person profile URL (linkedin.com/in/…or a Sales Navigator lead URL). Forfind_emailandfind_phone, any other LinkedIn URL is ignored and the other inputs must be enough on their own; forlinkedin_enrichmentit fails the row withBAD_LINKEDIN_URL.- For
linkedin_enrichment,emailand the name combination are only used when nolinkedinUrlis given. - A row missing these inputs fails with
MISSING_INPUTS; forverify, withMISSING_EMAILwhenemailis absent andBAD_EMAILwhen it is not a valid email. - Requesting
find_emailandverifyin the same row runs only one of them:verifywhenemailis a valid email,find_emailotherwise.
<…> sequence, and input may only hold the input fields: anything else rejects the whole call with WRONG_INPUT_FORMAT.
Metadata
Themetadata field can be a string or an object whose values are strings, each of at most 400 characters and without any <…> sequence. It is returned in the API response and in the webhooks, allowing you to track and correlate enrichment requests. Any other value rejects the whole call with WRONG_METADATA_FORMAT.
Response
The API returns an array where each element corresponds to a request in the input array, in the same order. A started request returns an enrichmentid; a request that could not be started returns an error code and a readable message.
{
"id": "enr_ExampleA1b2C3d4E5",
"metadata": {
"crmId": "12345"
}
}
{
"error": "MISSING_INPUTS",
"message": "Missing LinkedIn url OR the combination of first name, last name, company name, company domain",
"metadata": "12345"
}
error codes are listed in Request errors.
Getting Results
Check Enrich Data for details on the enrichment result structure.
- Webhooks (recommended): your team’s enrichment webhooks, and the
webhookUrlquery parameter when given, receive an event for each enrichment as soon as it is over - Polling: Use the Get Enrichment Result endpoint with the returned enrichment ID
Request error codes
These reject the whole call with a 400 (405 forMETHOD_NOT_ALLOWED) and a {"error": "<CODE>"} body. No enrichment is started.
| Error Code | Description |
|---|---|
WRONG_BODY_FORMAT | The body must be a JSON array |
NO_ENRICHMENTS_REQUESTED | The body must contain at least one enrichment |
TOO_MANY_ENRICHMENTS_REQUESTED | Maximum 500 enrichments per request |
WRONG_INPUT_FORMAT | An input is not an object, has a key that is not an input field, or a value that is not a string, is longer than 400 characters or contains a <…> sequence |
WRONG_METADATA_FORMAT | A metadata is neither a string nor an object whose values are strings, or one of its strings is longer than 400 characters or contains a <…> sequence |
WRONG_ENRICHMENT_REQUEST_FORMAT | An enrichmentRequests is not an array |
NO_WORKFLOW_REQUESTED | An enrichmentRequests is empty |
UNAUTHORIZED_WORKFLOW_REQUESTED | An enrichmentRequests holds an unknown enrichment type |
WRONG_WEBHOOK_URL | The webhookUrl query parameter is not a valid URL |
METHOD_NOT_ALLOWED | The endpoint only accepts POST |
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
Authorizations
Query Parameters
Body
application/json
Maximum array length:
500Enrichment types to perform, at least one of: find_email, find_phone, verify, linkedin_enrichment. Requesting find_email and verify together runs only one of them: verify when input.email is a valid email, find_email otherwise.
Available options:
find_email, find_phone, verify, linkedin_enrichment Example:
["find_email", "verify"]
Response
One item per row, in the order of the request: an enrichment id, or an error code with its message when the row could not be started
Why the row was not started. See the request errors of the Enrichment object.
Available options:
BAD_EMAIL, BAD_LINKEDIN_URL, MISSING_EMAIL, MISSING_INPUTS, MISSING_FUNDS, CREDITS_USAGE_FORBIDDEN, NOT_ALLOWED_EMAIL, NOT_ALLOWED_PHONE, NOT_ALLOWED_LINKEDIN, NOT_ALLOWED_VERIFY, LINKEDIN_UNSUBSCRIBED, TEAM_BLOCKED, TEAM_IN_ERROR, SYSTEM_DISABLED, NO_AVAILABLE_PROVIDER Was this page helpful?