{
"enrichmentId": "<string>",
"input": {},
"data": {
"email": {
"email": "jsmith@example.com",
"notFound": true
},
"phone": {
"phone": "<string>",
"additionalPhones": [
"<string>"
],
"notFound": true
},
"linkedin": {}
},
"failedWorkflows": [],
"reason": "<string>",
"error": "<string>"
}Enrichment
find_email), find their phone number (find_phone), verify an email
(verify) or enrich their LinkedIn profile (linkedin_enrichment). Start one
with Enrich Data,
Enrich Lead or many at once with
Bulk Enrich Data. Each call
answers with an enrichment id (enr_…) right away and the work runs in the
background.
There are two ways to get the result:
- Webhooks (recommended): lemlist calls your endpoint once the enrichment is over. See Webhooks below.
- Polling: call Get Enrichment Result
with the
iduntilenrichmentStatusis no longerin-progress.
Result keys
Polling and webhooks carry the same per-workflow results, under different key names:| Workflow | Key in GET /enrich/{enrichId} data | Key in webhook data |
|---|---|---|
find_email | email | find_email |
verify | email.status | verify.status |
find_phone | phone | find_phone |
linkedin_enrichment | linkedin | linkedin_enrichment |
find_email or find_phone that found nothing still produced a result: its
key is present with notFound: true. failedWorkflows lists the requested
workflows that ended without any result; they have no key in data. A workflow
lemlist runs on its own as a dependency of a requested one is never listed.
failedWorkflows is only present when it is not empty.
When the person opted out of enrichment, the value is never returned:
notFound is true, as when nothing was found.
Request errors
When an enrichment cannot be started, the start call answers with acode naming why and a message explaining it. Bulk rows carry them as
error and message. message is a human-readable text that may be
translated to the language of the API user: branch on code (error on bulk
rows), never on message.
| Code | Meaning |
|---|---|
BAD_EMAIL | Invalid email format |
BAD_LINKEDIN_URL | Invalid LinkedIn URL format: linkedin_enrichment needs a person profile URL |
MISSING_EMAIL | Email address is required for verification |
MISSING_INPUTS | Not enough inputs for the requested workflow (see the required inputs in Bulk Enrich Data) |
MISSING_FUNDS | Not enough credits to complete this enrichment |
CREDITS_USAGE_FORBIDDEN | User LinkedIn account needs to be connected in “Settings” to enrich |
NOT_ALLOWED_EMAIL | You don’t have permission to find emails |
NOT_ALLOWED_PHONE | You don’t have permission to find phone numbers |
NOT_ALLOWED_LINKEDIN | You don’t have permission to enrich LinkedIn profiles |
NOT_ALLOWED_VERIFY | You don’t have permission to verify emails |
LINKEDIN_UNSUBSCRIBED | This LinkedIn profile is on the privacy list and cannot be enriched |
TEAM_BLOCKED | The enrichment process is blocked on your team. Please contact support for assistance. |
TEAM_IN_ERROR | The enrichment process is blocked on your team. Please contact support for assistance. Temporary: retry later. |
SYSTEM_DISABLED | Enrichment service is temporarily unavailable, please retry later |
NO_AVAILABLE_PROVIDER | No enrichment provider is available for this request |
403 for CREDITS_USAGE_FORBIDDEN, 503 for
TEAM_IN_ERROR and SYSTEM_DISABLED (retry later), 400 for the others.
Failure codes
An enrichment that started but failed as a whole answersfailed on
Get Enrichment Result
and sends an enrichmentError webhook, with a code and a reason. reason
is a human-readable text that may be translated to the language of the API
user: branch on code, never on reason.
| Code | Meaning |
|---|---|
FAILED_TO_PROCESS | Enrichment service is having issues, please retry later |
INVALID_INPUT | The provided data is invalid |
PROVIDER_TIMEOUT | The enrichment provider did not respond in time |
PROVIDER_REJECTED | The enrichment provider could not process this request |
Webhooks
Enrichments send two webhook events:| Event | When |
|---|---|
enrichmentDone | The enrichment is over. Some requested workflows may have ended without any result: check failedWorkflows. |
enrichmentError | The enrichment failed as a whole. |
webhookUrl passed when the enrichment was started. A POST is sent with a
JSON body holding the event type and a data array. The array can hold
several enrichments of the same event: lemlist may group them in one call.
Each enrichmentDone item:
| Field | Type | Description |
|---|---|---|
id | string | Enrichment ID |
data.find_email | object | email (absent when not found), notFound, status (deliverable, risky or undeliverable, when a check resolved) |
data.verify | object | status: deliverable, risky or undeliverable |
data.find_phone | object | phone (absent when not found), additionalPhones (only when the provider returned more numbers), notFound |
data.linkedin_enrichment | object | The LinkedIn profile |
failedWorkflows | string[] | Requested workflows that ended without any result, absent from data. A find_email or find_phone that found nothing is not listed: it answers notFound: true. Only present when not empty |
metadata | string or object | The metadata sent with the bulk request, {} when none was sent |
enrichmentError item:
| Field | Type | Description |
|---|---|---|
id | string | Enrichment ID |
code | string | One of the failure codes |
reason | string | Human-readable explanation of code, possibly translated to the language of the API user. Branch on code |
error | string | Raw cause stored on the enrichment, absent when none was stored. Prefer code |
metadata | string or object | The metadata sent with the bulk request, {} when none was sent |
{
"type": "enrichmentDone",
"data": [
{
"id": "enr_ExampleA1b2C3d4E5",
"data": {
"find_email": {
"email": "john@example.com",
"notFound": false,
"status": "deliverable"
},
"find_phone": {
"phone": "+15555550100",
"additionalPhones": ["+15555550101"],
"notFound": false
}
},
"failedWorkflows": ["linkedin_enrichment"],
"metadata": {
"crmId": "12345"
}
}
]
}
{
"type": "enrichmentError",
"data": [
{
"id": "enr_ExampleF6g7H8i9J0",
"code": "PROVIDER_TIMEOUT",
"reason": "The enrichment provider did not respond in time",
"error": "PROVIDER_TIMEOUT",
"metadata": {}
}
]
}
An enrichment: one request to find an email or a phone number, verify an email or enrich a LinkedIn profile for one person. This is the shape GET /enrich/{enrichId} answers with; webhooks carry the same results under other key names (see the Webhooks section).
Identifier of the enrichment
Lifecycle state of the enrichment, not to be confused with data.email.status. Each state comes with its own HTTP status: done 200, in-progress 202, failed 400, not-found 404. A cancelled enrichment answers done.
done, in-progress, failed, not-found The inputs the enrichment was started with, echoed back. Absent on not-found.
What the enrichment found, keyed by result. Empty unless enrichmentStatus is done. A key is present only for a requested workflow that produced a result. A find_email or find_phone that found nothing still has its key, with notFound: true. A requested workflow that ended without any result has no key and is listed in failedWorkflows.
Show child attributes
Show child attributes
On done, the requested workflows that ended without any result; they have no key in data. A find_email or find_phone that found nothing is not listed: it answers notFound: true in data. A workflow lemlist runs on its own as a dependency of a requested one is never listed. Only present when not empty.
find_email, find_phone, verify, linkedin_enrichment On failed, why the enrichment failed. An unknown or missing cause reads as FAILED_TO_PROCESS.
FAILED_TO_PROCESS, INVALID_INPUT, PROVIDER_TIMEOUT, PROVIDER_REJECTED On failed, a human-readable explanation of code, possibly translated to the language of the API user. Branch on code, never on reason.
On failed, the raw cause stored on the enrichment, absent when none was stored; prefer code. On not-found, Enrichment not found.
Was this page helpful?