Enrich Contacts
Reveal full contact data for contacts you’ve already found via Search Contacts.
Pass up to 100 contact ids (from the search response). Use the reveal field to control what gets unlocked:
emails- work and personal email addressesphones- mobile and direct phone numbers- Omit
revealto get both by default
Waterfall Reveal
Fall through to your enabled third-party providers when Lusha’s own data has no match, for extra reach on hard-to-match contacts.
If Data Waterfall is enabled on your account, with specific providers turned on under Account > Waterfall, the waterfall runs automatically on every Enrich Contacts call - you don’t need to pass anything to trigger it.
Pass waterfallEnabled: false to opt a specific call out:
"reveal": ["emails", "phones"],
"waterfallEnabled": false
revealcontrols which fields come back.waterfallEnabledcontrols whether the waterfall runs for this call at all. Defaults totruewhenever Data Waterfall is enabled on your account; passfalseto disable it just for this call.- Provider order isn’t configurable - Lusha manages that internally.
- If Data Waterfall is off or no providers are enabled on your account,
waterfallEnabledhas no effect either way.
When the waterfall runs, the response adds status, statusDescription and (when a field is empty because the waterfall did not run) statusReason. Each email and phone carries dataSource (lusha or <providerId>), plus credits when an external provider delivered it. Contacts with unresolved data points list them in missingDataPoints. These fields are omitted when the waterfall did not run, so a Lusha-only response keeps its usual shape.
Async results (job)
Fast providers answer inside this call. A slower provider does not hold the request open: the response returns what is already known, plus a job.
- If the response has no
job, it is final. - If
jobis present, waitjob.retryAfterseconds, then call Get Contacts Enrich Job withjob.id. - While the job
statusisprocessing, waitretryAfterseconds and poll again. - On
complete, merge the job’scontactsinto your enrich results byid. Do not replace the whole enrich payload. - On
expiredorfailed, stop and keep what Enrich Contacts already returned.
Branch on whether job is present, and then on the job status. Don’t infer that work is still running because an email or phone is empty.
Polling is free. A data point is billed once, by whichever call delivered it.
Tip: If
canReveal.creditsis0in the search response, that data has already been revealed for your account - re-enriching it is free.
Billing: Charged per revealed field (email or phone) via per-datapoint pricing.
Persisting to a table: Pass
tableIdto also add these contacts to an existing table and populate the Work email / Phone columns. See Contacts Tables.
curl --request POST \
--url https://api.lusha.com/v3/contacts/enrich \
--header 'Content-Type: application/json' \
--header 'api_key: <api-key>' \
--data '
{
"ids": [
"4389064654",
"4389064624"
],
"reveal": [
"emails",
"phones"
]
}
'{
"requestId": "71581363-f73d-46e1-9115-ecbd771b964b",
"results": [
{
"id": "4389064654",
"firstName": "Daniel",
"lastName": "Turgeman",
"fullName": "Daniel Turgeman",
"jobTitle": {
"title": "Technical Product Manager",
"departments": [
"Product"
],
"seniority": "Manager"
},
"location": {
"country": "Israel",
"countryIso2": "IL",
"city": "Tel Aviv",
"continent": "Asia",
"coordinates": [
34.78057098388672,
32.08087921142578
],
"isEuContact": false
},
"tags": [],
"emails": [
{
"email": "daniel.t@lusha.com",
"type": "work",
"confidence": "A+",
"updateDate": "2026-04-23"
}
],
"phones": [],
"company": {
"id": "16303253",
"name": "Lusha",
"domain": "www.lusha.com",
"industry": "Technology, Information & Media"
},
"socialLinks": {
"linkedin": "https://www.linkedin.com/in/daniel-turgeman-49676b161"
},
"previousEmployment": [],
"updateDate": "2026-04-23"
}
],
"billing": {
"creditsCharged": 2,
"resultsReturned": 2
}
}Authorizations
Body
Whether this call is allowed to fall through to your enabled
third-party providers when Lusha's own data has no match, for the fields
requested via reveal. Defaults to true whenever Data Waterfall is
enabled on your account (Account > Waterfall) - pass false to opt this
specific call out. Has no effect if Data Waterfall or no providers are
enabled on your account. Provider order isn't configurable - Lusha manages
that internally.
false means Lusha data only. If Lusha does not have a requested field, the response sets statusReason: WATERFALL_DISABLED.
false
Response
Successful response
Waterfall outcome for the request. Omitted when the waterfall did not run.
completed- every requested data point was resolved.partial- at least one requested data point is still missing, or still in progress whenjobis present.halted- the run stopped before it finished the provider list.OUT_OF_CREDITS- the run stopped because the account could not pay.PARTIAL_OUT_OF_CREDITS- some data was returned, then credits ran out.
completed, partial, halted, OUT_OF_CREDITS, PARTIAL_OUT_OF_CREDITS "partial"
Stable reason a requested field is empty because the waterfall did not run. When set, status is partial.
WATERFALL_NOT_CONFIGURED- Data Waterfall is on the plan, but no providers are connected.WATERFALL_NOT_IN_PLAN- Data Waterfall is not on the account's plan.WATERFALL_DISABLED- the request setwaterfallEnabledtofalse, and Lusha did not have the field.
WATERFALL_NOT_CONFIGURED, WATERFALL_NOT_IN_PLAN, WATERFALL_DISABLED Was this page helpful?
curl --request POST \
--url https://api.lusha.com/v3/contacts/enrich \
--header 'Content-Type: application/json' \
--header 'api_key: <api-key>' \
--data '
{
"ids": [
"4389064654",
"4389064624"
],
"reveal": [
"emails",
"phones"
]
}
'{
"requestId": "71581363-f73d-46e1-9115-ecbd771b964b",
"results": [
{
"id": "4389064654",
"firstName": "Daniel",
"lastName": "Turgeman",
"fullName": "Daniel Turgeman",
"jobTitle": {
"title": "Technical Product Manager",
"departments": [
"Product"
],
"seniority": "Manager"
},
"location": {
"country": "Israel",
"countryIso2": "IL",
"city": "Tel Aviv",
"continent": "Asia",
"coordinates": [
34.78057098388672,
32.08087921142578
],
"isEuContact": false
},
"tags": [],
"emails": [
{
"email": "daniel.t@lusha.com",
"type": "work",
"confidence": "A+",
"updateDate": "2026-04-23"
}
],
"phones": [],
"company": {
"id": "16303253",
"name": "Lusha",
"domain": "www.lusha.com",
"industry": "Technology, Information & Media"
},
"socialLinks": {
"linkedin": "https://www.linkedin.com/in/daniel-turgeman-49676b161"
},
"previousEmployment": [],
"updateDate": "2026-04-23"
}
],
"billing": {
"creditsCharged": 2,
"resultsReturned": 2
}
}