Search and Enrich Contacts

POST

contacts

search-and-enrich

curl --request POST \
  --url https://api.lusha.com/v3/contacts/search-and-enrich \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "contacts": [
    {
      "clientReferenceId": "my-ref-1",
      "firstName": "Orit",
      "lastName": "Shilvock",
      "companyName": "Lusha",
      "companyDomain": "lusha.com"
    },
    {
      "clientReferenceId": "my-ref-2",
      "linkedinUrl": "https://www.linkedin.com/in/shmulikwillinger"
    }
  ],
  "reveal": [
    "emails",
    "phones"
  ],
  "options": {
    "includePartialProfiles": true
  }
}
'

import requests

url = "https://api.lusha.com/v3/contacts/search-and-enrich"

payload = {
    "contacts": [
        {
            "clientReferenceId": "my-ref-1",
            "firstName": "Orit",
            "lastName": "Shilvock",
            "companyName": "Lusha",
            "companyDomain": "lusha.com"
        },
        {
            "clientReferenceId": "my-ref-2",
            "linkedinUrl": "https://www.linkedin.com/in/shmulikwillinger"
        }
    ],
    "reveal": ["emails", "phones"],
    "options": { "includePartialProfiles": True }
}
headers = {
    "api_key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_key: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contacts: [
      {
        clientReferenceId: 'my-ref-1',
        firstName: 'Orit',
        lastName: 'Shilvock',
        companyName: 'Lusha',
        companyDomain: 'lusha.com'
      },
      {
        clientReferenceId: 'my-ref-2',
        linkedinUrl: 'https://www.linkedin.com/in/shmulikwillinger'
      }
    ],
    reveal: ['emails', 'phones'],
    options: {includePartialProfiles: true}
  })
};

fetch('https://api.lusha.com/v3/contacts/search-and-enrich', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.lusha.com/v3/contacts/search-and-enrich")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"contacts\": [\n    {\n      \"clientReferenceId\": \"my-ref-1\",\n      \"firstName\": \"Orit\",\n      \"lastName\": \"Shilvock\",\n      \"companyName\": \"Lusha\",\n      \"companyDomain\": \"lusha.com\"\n    },\n    {\n      \"clientReferenceId\": \"my-ref-2\",\n      \"linkedinUrl\": \"https://www.linkedin.com/in/shmulikwillinger\"\n    }\n  ],\n  \"reveal\": [\n    \"emails\",\n    \"phones\"\n  ],\n  \"options\": {\n    \"includePartialProfiles\": true\n  }\n}")
  .asString();

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lusha.com/v3/contacts/search-and-enrich"

	payload := strings.NewReader("{\n  \"contacts\": [\n    {\n      \"clientReferenceId\": \"my-ref-1\",\n      \"firstName\": \"Orit\",\n      \"lastName\": \"Shilvock\",\n      \"companyName\": \"Lusha\",\n      \"companyDomain\": \"lusha.com\"\n    },\n    {\n      \"clientReferenceId\": \"my-ref-2\",\n      \"linkedinUrl\": \"https://www.linkedin.com/in/shmulikwillinger\"\n    }\n  ],\n  \"reveal\": [\n    \"emails\",\n    \"phones\"\n  ],\n  \"options\": {\n    \"includePartialProfiles\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "requestId": "211ee5da-3c0d-4621-9fa5-140e393a3ced",
  "results": [
    {
      "clientReferenceId": "my-ref-1",
      "id": "4389064704",
      "firstName": "Orit",
      "lastName": "Shilvock",
      "fullName": "Orit Shilvock",
      "emails": [
        {
          "email": "orit.shilvock@lusha.com",
          "type": "work",
          "confidence": "A+",
          "updateDate": "2026-04-23"
        }
      ],
      "phones": [],
      "tags": [],
      "previousEmployment": [],
      "updateDate": "2026-04-23"
    }
  ],
  "billing": {
    "creditsCharged": 2,
    "resultsReturned": 2
  }
}

Use this endpoint to find contacts and reveal their full data in one request - it combines Search Contacts and Enrich Contacts into a single call. Provide identifiers the same way you would for Search Contacts, then use reveal to control what gets unlocked.

If you need to inspect what’s revealable and its credit cost before committing to a reveal, call Search Contacts first, then Enrich Contacts separately. Use this combined endpoint when you already know you want the full profile.

Endpoint

POST https://api.lusha.com/v3/contacts/search-and-enrich

Authentication

string

required

Your Lusha API key.

Accepted identifiers

Each contact in the contacts array needs one of the following:

Lusha contact id
linkedinUrl
email
firstName and lastName and (companyName or companyDomain)

Request body

array

required

Up to 100 contacts to find and enrich.

Show contact fields

string

Your own reference ID for this contact. Echoed back on the matching result.Example: my-ref-1

string

A Lusha contact ID.

string

The contact’s LinkedIn profile URL.

string

The contact’s email address.

string

First name. Requires lastName and either companyName or companyDomain.

string

Last name. Requires firstName and either companyName or companyDomain.

string

The contact’s current company name.

string

The contact’s current company domain.

string[]

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

object

Show options fields

boolean

When true, includes contacts with incomplete data in the results instead of dropping them.

Response

string

Unique ID for this request, in UUID format.

object[]

One entry per contact you searched for. Each result has the same shape as an Enrich Contacts result, plus clientReferenceId.

Show result fields

string

Echoes the clientReferenceId you sent for this contact.

string

The Lusha contact ID.

string

object

Title, departments, and seniority.

object

Country, state, city, continent, city-level coordinates (not street or neighborhood), and EU flag.

integer

LinkedIn follower count.

integer

LinkedIn connection count.

object

LinkedIn profile details: skills (strings), certifications (name, authority), awards (title, date), and courses (name). Each list is omitted when Lusha has no data for it. See Enrich Contacts for the full shape.

boolean

Whether this is a partial profile.

object[]

Present when reveal includes (or omits) emails. Each entry has email, type, confidence, and updateDate, plus dataSource and credits when Data Waterfall ran.

object[]

Present when reveal includes (or omits) phones. Each entry has number, type, doNotCall, and updateDate, plus dataSource and credits when Data Waterfall ran.

object

Company id, name, domain, and industry.

LinkedIn and X profile URLs.

object[]

Prior roles.

object[]

Tags applied to this contact in Lusha.

string

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

object[]

Requested data points the waterfall couldn’t resolve, each with type (email or phone), status (NOT_FOUND or BILLING_FAILED), and description. Present only when the waterfall ran. See Enrich Contacts for details.

object

Present instead of profile data when the lookup or reveal fails for this contact.

Show properties

string

One of NOT_FOUND, COMPLIANCE_RESTRICTED, ENRICH_FAILED.

string

Human-readable description.

object

Show properties

integer

Total 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.

Search and Enrich Contacts never returns a job. Only Enrich Contacts can hand off to an async Data Waterfall job.

Billing: Two charges apply - one for the search (api_search) and one per revealed field.

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/search-and-enrich \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contacts": [
      {
        "clientReferenceId": "my-ref-1",
        "firstName": "Orit",
        "lastName": "Shilvock",
        "companyName": "Lusha",
        "companyDomain": "lusha.com"
      }
    ],
    "reveal": ["emails", "phones"],
    "options": {
      "includePartialProfiles": true
    }
  }'

{
  "contacts": [
    {
      "clientReferenceId": "my-ref-1",
      "firstName": "Orit",
      "lastName": "Shilvock",
      "companyName": "Lusha",
      "companyDomain": "lusha.com"
    }
  ],
  "reveal": ["emails", "phones"],
  "options": {
    "includePartialProfiles": true
  }
}

Example response

{
  "requestId": "6e4b1192-9440-42c4-9a3e-793ddef6d73c",
  "results": [
    {
      "clientReferenceId": "my-ref-1",
      "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"
      }
    }
  ],
  "billing": {
    "creditsCharged": 3,
    "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

contacts

object[]

required

Required array length: 1 - 100 elements

Show child attributes

reveal

enum<string>[]

Available options:

emails,

phones

Example:

["emails", "phones"]

options

object

Additional options for search requests

Show child attributes

Response

Successful response

requestId

string<uuid>

results

object[]

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

⌘I

Search and Enrich Contacts

curl --request POST \
  --url https://api.lusha.com/v3/contacts/search-and-enrich \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "contacts": [
    {
      "clientReferenceId": "my-ref-1",
      "firstName": "Orit",
      "lastName": "Shilvock",
      "companyName": "Lusha",
      "companyDomain": "lusha.com"
    },
    {
      "clientReferenceId": "my-ref-2",
      "linkedinUrl": "https://www.linkedin.com/in/shmulikwillinger"
    }
  ],
  "reveal": [
    "emails",
    "phones"
  ],
  "options": {
    "includePartialProfiles": true
  }
}
'

import requests

url = "https://api.lusha.com/v3/contacts/search-and-enrich"

payload = {
    "contacts": [
        {
            "clientReferenceId": "my-ref-1",
            "firstName": "Orit",
            "lastName": "Shilvock",
            "companyName": "Lusha",
            "companyDomain": "lusha.com"
        },
        {
            "clientReferenceId": "my-ref-2",
            "linkedinUrl": "https://www.linkedin.com/in/shmulikwillinger"
        }
    ],
    "reveal": ["emails", "phones"],
    "options": { "includePartialProfiles": True }
}
headers = {
    "api_key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_key: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contacts: [
      {
        clientReferenceId: 'my-ref-1',
        firstName: 'Orit',
        lastName: 'Shilvock',
        companyName: 'Lusha',
        companyDomain: 'lusha.com'
      },
      {
        clientReferenceId: 'my-ref-2',
        linkedinUrl: 'https://www.linkedin.com/in/shmulikwillinger'
      }
    ],
    reveal: ['emails', 'phones'],
    options: {includePartialProfiles: true}
  })
};

fetch('https://api.lusha.com/v3/contacts/search-and-enrich', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.lusha.com/v3/contacts/search-and-enrich")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"contacts\": [\n    {\n      \"clientReferenceId\": \"my-ref-1\",\n      \"firstName\": \"Orit\",\n      \"lastName\": \"Shilvock\",\n      \"companyName\": \"Lusha\",\n      \"companyDomain\": \"lusha.com\"\n    },\n    {\n      \"clientReferenceId\": \"my-ref-2\",\n      \"linkedinUrl\": \"https://www.linkedin.com/in/shmulikwillinger\"\n    }\n  ],\n  \"reveal\": [\n    \"emails\",\n    \"phones\"\n  ],\n  \"options\": {\n    \"includePartialProfiles\": true\n  }\n}")
  .asString();

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lusha.com/v3/contacts/search-and-enrich"

	payload := strings.NewReader("{\n  \"contacts\": [\n    {\n      \"clientReferenceId\": \"my-ref-1\",\n      \"firstName\": \"Orit\",\n      \"lastName\": \"Shilvock\",\n      \"companyName\": \"Lusha\",\n      \"companyDomain\": \"lusha.com\"\n    },\n    {\n      \"clientReferenceId\": \"my-ref-2\",\n      \"linkedinUrl\": \"https://www.linkedin.com/in/shmulikwillinger\"\n    }\n  ],\n  \"reveal\": [\n    \"emails\",\n    \"phones\"\n  ],\n  \"options\": {\n    \"includePartialProfiles\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "requestId": "211ee5da-3c0d-4621-9fa5-140e393a3ced",
  "results": [
    {
      "clientReferenceId": "my-ref-1",
      "id": "4389064704",
      "firstName": "Orit",
      "lastName": "Shilvock",
      "fullName": "Orit Shilvock",
      "emails": [
        {
          "email": "orit.shilvock@lusha.com",
          "type": "work",
          "confidence": "A+",
          "updateDate": "2026-04-23"
        }
      ],
      "phones": [],
      "tags": [],
      "previousEmployment": [],
      "updateDate": "2026-04-23"
    }
  ],
  "billing": {
    "creditsCharged": 2,
    "resultsReturned": 2
  }
}

Overview

Resources

Endpoints

Endpoint

Authentication

Accepted identifiers

Request body

Response

Error codes

Example

Authorizations

Body

Response

​Endpoint

​Authentication

​Accepted identifiers

​Request body

​Response

​Error codes

​Example

Authorizations

Body

Response

Endpoint

Authentication

Accepted identifiers

Request body

Response

Error codes

Example