Enrich

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 addresses
phones - mobile and direct phone numbers
Omit reveal to 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

reveal controls which fields come back.
waterfallEnabled controls whether the waterfall runs for this call at all. Defaults to true whenever Data Waterfall is enabled on your account; pass false to 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, waterfallEnabled has 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 job is present, wait job.retryAfter seconds, then call Get Contacts Enrich Job with job.id.
While the job status is processing, wait retryAfter seconds and poll again.
On complete, merge the job’s contacts into your enrich results by id. Do not replace the whole enrich payload.
On expired or failed, 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.credits is 0 in 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 tableId to also add these contacts to an existing table and populate the Work email / Phone columns. See Contacts Tables.

POST

contacts

enrich

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

api_key

string

header

required

Your Lusha API key. You can find this in your Lusha dashboard under API settings. Include this key in the api_key header for all requests.

Body

application/json

ids

string[]

required

Required array length: 1 - 100 elements

Example:

["4389064654", "4389064624"]

reveal

enum<string>[]

Available options:

emails,

phones

Example:

["emails", "phones"]

waterfallEnabled

boolean

default:true

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.

Example:

false

tableId

string

Optional. If provided, these contacts are also added to this table (if not already present) and the revealed fields' columns are populated. See the Tables API.

Example:

"482910"

Response

Successful response

requestId

string<uuid>

results

object[]

Show child attributes

tableWrite

object

Added to a Prospecting, Enrich, Signals, or Lookalike response when tableId is passed on the request. The primary response is unaffected even if the table write fails.

Show child attributes

billing

object

Credit usage summary for a V3 API request

Show child attributes

status

enum<string>

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 when job is 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.

Available options:

completed,

partial,

halted,

OUT_OF_CREDITS,

PARTIAL_OUT_OF_CREDITS

Example:

"partial"

statusDescription

string

Human-readable text, present whenever status is set. Do not parse it - branch on status and statusReason.

Example:

"Some requested data points are still being retrieved."

statusReason

enum<string>

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 set waterfallEnabled to false, and Lusha did not have the field.

Available options:

WATERFALL_NOT_CONFIGURED,

WATERFALL_NOT_IN_PLAN,

WATERFALL_DISABLED

job

object

Present only when an async provider is still working. Absent means the response is final.

Show child attributes

⌘I

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
  }
}

Overview

Resources

Endpoints

Enrich Contacts

Waterfall Reveal

Async results (`job`)

Polling is free. A data point is billed once, by whichever call delivered it.

Authorizations

Body

Response