Enrich Contacts

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

Use this endpoint to reveal full contact data for contacts you’ve already found via Search Contacts. Pass the Lusha id from a search result, and choose what to unlock with reveal.

Enrich Contacts only works with id values returned by Search Contacts. It doesn’t accept email, linkedinUrl, or name-based identifiers. To search and reveal in one call, use Search and Enrich Contacts instead.

Endpoint

POST https://api.lusha.com/v3/contacts/enrich

Authentication

string

required

Your Lusha API key.

Request body

string[]

required

Up to 100 Lusha contact IDs, from a Search Contacts response.Example: ["4389064654", "4389064624"]

string[]

What to unlock for each contact. Omit this field to get both by default.Allowed values: emails, phones

Response

string

Unique ID for this request, in UUID format.

object[]

One entry per contact id you passed in.

Show result fields

string

The Lusha contact ID.

string

First name.

string

Last name.

string

Full name.

object

Show properties

string

Example: Vice President of Partnerships

string[]

Example: ["Business Development"]

string

Example: Vice President

object

Show properties

string

Example: Israel

string

Example: IL

string

Example: Tel Aviv District

string

Example: Tel Aviv

string

Example: Asia

number[]

City location coordinates: [longitude, latitude] of the city the contact is based in. City-level only - not a street address or neighborhood. Example: [34.78057, 32.08088]

boolean

Whether the contact is located in the EU.

object[]

Present when reveal includes (or omits) emails.

Show properties

string

Example: orit.shilvock@lusha.com

string

One of work, private, unknown.

string

Confidence score. Example: A+

string

Last-updated date, YYYY-MM-DD.

string

Where this data point came from: lusha, or the provider id when a Data Waterfall provider delivered it (for example wiza). Omitted when the waterfall didn’t run.

number

Credits charged for this data point. Present only when a Data Waterfall provider delivered it.

object[]

Present when reveal includes (or omits) phones.

Show properties

string

E.164 format. Example: +14155551234

string

One of mobile, direct, work, unknown.

boolean

Whether this number is on the Do Not Call list.

string

Last-updated date, YYYY-MM-DD.

string

Where this data point came from: lusha, or the provider id when a Data Waterfall provider delivered it (for example wiza). Omitted when the waterfall didn’t run.

number

Credits charged for this data point. Present only when a Data Waterfall provider delivered it.

object

Show properties

string

Example: 16303253

string

Example: Lusha

string

Example: www.lusha.com

string

Example: Technology, Information & Media

Show properties

string

LinkedIn profile URL.

string

X (Twitter) profile URL.

object[]

Prior roles.

Show properties

object

Show properties

string

object

Show properties

string

string[]

string

integer

Number of followers on the contact’s LinkedIn profile. Example: 1520

integer

Number of connections on the contact’s LinkedIn profile. Example: 500

object

Professional profile details from the contact’s LinkedIn profile. Each list is omitted when Lusha has no data for it. Check the has array in your Search Contacts response (skills, certifications, awards, courses) to see what’s available before enriching.

Show properties

string[]

Skills listed on the profile. Example: ["Python", "Project Management"]

object[]

Show properties

string

Certification name. Example: AWS Certified Solutions Architect - Associate

string

Issuing organization. Example: Amazon Web Services

object[]

Show properties

string

Award title. Example: Employee of the Year

string

Year the award was received. Example: 2019

object[]

Show properties

string

Course name. Example: Machine Learning

boolean

Whether this is a partial profile. Search and Prospecting return partial profiles only when options.includePartialProfiles is true.

object[]

Tags you’ve applied to this contact in Lusha.

Show properties

string

Hex code. Example: #FF5733

string

Date the record was last updated, YYYY-MM-DD.

object[]

Present when the waterfall ran and at least one requested data point is still unresolved. At most one entry for email and one for phone.

Show properties

string

email or phone.

string

NOT_FOUND - every source was searched and nothing was found. BILLING_FAILED - the run stopped on credits before the field was fully searched.

string

Human-readable text. Don’t parse it.

object

Present instead of profile data when enrichment fails for this id.

Show properties

string

One of NOT_FOUND, COMPLIANCE_RESTRICTED, ENRICH_FAILED.

string

Human-readable description.

object

Show properties

integer

Credits charged for this request.

integer

Number of successful results.

string

Data Waterfall outcome for the request. Omitted when the waterfall didn’t run. One of completed, partial, halted, OUT_OF_CREDITS, PARTIAL_OUT_OF_CREDITS.

string

Human-readable text, present whenever status is set. Don’t parse it - branch on status and statusReason.

string

Why a requested field is empty when the waterfall didn’t run: WATERFALL_NOT_CONFIGURED, WATERFALL_NOT_IN_PLAN, or WATERFALL_DISABLED. When set, status is partial.

object

Present only when a slower Data Waterfall provider is still working. Absent means the response is final. Poll it with Get Contacts Enrich Job.

Show properties

string

Pass this as jobId to GET /v3/contacts/jobs/{jobId}. Example: wf_3f2b9c1e-4a7d-4f3b-9c2e-1d6a5b8c7e90

string

Always processing on this response.

string

ISO timestamp. After this, the job is gone.

number

Seconds to wait before the first poll.

object

Present only when you pass tableId on the request. Summarizes what was written to the table. The rest of the response is unaffected even if the table write fails.

Show properties

string

The table that was written to. Example: 482910

integer

New entities added to the table by this call.

integer

Entities from this call that were already in the table.

integer

Columns auto-created by this call, for example a Signals column created on first use.

integer

Rows the column run touched as part of this call.

integer

Rows that incurred a credit charge.

integer

Rows already paid for in this table, which were not charged again.

integer

Credits charged for this table write.

Billing: Charged per revealed field (email or phone) via per-datapoint pricing.

Error codes

Status	Meaning
`400`	Bad request - invalid input data
`401`	Unauthorized - invalid or missing API key
`402`	Payment required - insufficient credits
`403`	Forbidden - account inactive or V3 access not enabled
`429`	Too many requests - rate limit exceeded

Example

curl --request POST \
  --url https://api.lusha.com/v3/contacts/enrich \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ids": ["4389064654", "4389064624"],
    "reveal": ["emails", "phones"]
  }'

{
  "ids": ["4389064654", "4389064624"],
  "reveal": ["emails", "phones"]
}

Example response

{
  "requestId": "6e4b1192-9440-42c4-9a3e-793ddef6d73c",
  "results": [
    {
      "id": "4389064654",
      "firstName": "Orit",
      "lastName": "Shilvock",
      "fullName": "Orit Shilvock",
      "jobTitle": {
        "title": "Vice President of Partnerships",
        "departments": ["Business Development"],
        "seniority": "Vice President"
      },
      "location": {
        "country": "Israel",
        "countryIso2": "IL",
        "city": "Tel Aviv",
        "continent": "Asia"
      },
      "emails": [
        { "email": "orit.shilvock@lusha.com", "type": "work", "confidence": "A+", "updateDate": "2026-04-23" }
      ],
      "phones": [
        { "number": "+14155551234", "type": "mobile", "doNotCall": false, "updateDate": "2026-04-23" }
      ],
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com",
        "industry": "Technology, Information & Media"
      },
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/orit-shilvock-6243bb5"
      },
      "updateDate": "2026-04-23"
    }
  ],
  "billing": {
    "creditsCharged": 2,
    "resultsReturned": 1
  }
}

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

Endpoint

Authentication

Request body

Response

Error codes

Example

Authorizations

Body

Response

​Endpoint

​Authentication

​Request body

​Response

​Error codes

​Example

Authorizations

Body

Response

Endpoint

Authentication

Request body

Response

Error codes

Example