Search Contacts

POST

contacts

Search Contacts

curl --request POST \
  --url https://api.lusha.com/v3/contacts/search \
  --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"
    },
    {
      "clientReferenceId": "my-ref-3",
      "email": "gal.ashkelon@lusha.com"
    },
    {
      "clientReferenceId": "my-ref-4",
      "id": "12345"
    }
  ],
  "options": {
    "includePartialProfiles": true
  }
}
'

import requests

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

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"
        },
        {
            "clientReferenceId": "my-ref-3",
            "email": "gal.ashkelon@lusha.com"
        },
        {
            "clientReferenceId": "my-ref-4",
            "id": "12345"
        }
    ],
    "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'
      },
      {clientReferenceId: 'my-ref-3', email: 'gal.ashkelon@lusha.com'},
      {clientReferenceId: 'my-ref-4', id: '12345'}
    ],
    options: {includePartialProfiles: true}
  })
};

fetch('https://api.lusha.com/v3/contacts/search', 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")
  .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      \"clientReferenceId\": \"my-ref-3\",\n      \"email\": \"gal.ashkelon@lusha.com\"\n    },\n    {\n      \"clientReferenceId\": \"my-ref-4\",\n      \"id\": \"12345\"\n    }\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"

	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      \"clientReferenceId\": \"my-ref-3\",\n      \"email\": \"gal.ashkelon@lusha.com\"\n    },\n    {\n      \"clientReferenceId\": \"my-ref-4\",\n      \"id\": \"12345\"\n    }\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": "6e4b1192-9440-42c4-9a3e-793ddef6d73c",
  "results": [
    {
      "clientReferenceId": "my-ref-1",
      "id": "4415824633",
      "firstName": "Orit",
      "lastName": "Shilvock",
      "jobTitle": {
        "title": "Vice President of Partnerships",
        "departments": [
          "Business Development"
        ],
        "seniority": "Vice President"
      },
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com",
        "industry": "Technology, Information & Media"
      },
      "location": {
        "country": "Israel",
        "city": "Tel Aviv"
      },
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/orit-shilvock-6243bb5"
      },
      "has": [
        "firstName",
        "lastName",
        "jobTitle",
        "location",
        "socialLinks",
        "emails"
      ],
      "canReveal": [
        {
          "field": "emails",
          "credits": 1
        }
      ]
    },
    {
      "clientReferenceId": "my-ref-2",
      "id": "4415824679",
      "firstName": "Shmulik",
      "lastName": "Willinger",
      "jobTitle": {
        "title": "Chief Architect",
        "departments": [
          "Engineering & Technical"
        ],
        "seniority": "C-Suite"
      },
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com",
        "industry": "Technology, Information & Media"
      },
      "location": {
        "country": "Israel",
        "city": "Tel Aviv"
      },
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/shmulikwillinger"
      },
      "has": [
        "firstName",
        "lastName",
        "jobTitle",
        "location",
        "socialLinks",
        "emails"
      ],
      "canReveal": [
        {
          "field": "emails",
          "credits": 1
        }
      ]
    },
    {
      "clientReferenceId": "my-ref-3",
      "id": "4415824664",
      "firstName": "Gal",
      "lastName": "Ashkelon",
      "jobTitle": {
        "title": "Global Partner Program Manager",
        "departments": [
          "Business Development"
        ],
        "seniority": "Manager"
      },
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com",
        "industry": "Technology, Information & Media"
      },
      "location": {
        "country": "Israel",
        "city": "Tel Aviv"
      },
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/gal-ashkelon-39408557"
      },
      "has": [
        "firstName",
        "lastName",
        "jobTitle",
        "location",
        "socialLinks",
        "emails"
      ],
      "canReveal": [
        {
          "field": "emails",
          "credits": 1
        }
      ]
    },
    {
      "clientReferenceId": "my-ref-4",
      "error": {
        "code": "NOT_FOUND",
        "message": "Contact not found"
      }
    }
  ],
  "billing": {
    "creditsCharged": 1,
    "resultsReturned": 3
  }
}

Use this endpoint to look up contacts by identifier and get back a non-PII preview of each matching profile - no emails or phone numbers. Each result’s has field lists the data points already available, and canReveal lists what you can unlock (and its credit cost) by calling Enrich Contacts.

Endpoint

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

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)

Attach a clientReferenceId to each contact so you can match results back to your input - the array of results isn’t guaranteed to preserve input order.

Request body

array

required

Up to 100 contacts to look up.

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.Example: 12345

string

The contact’s LinkedIn profile URL.Example: https://www.linkedin.com/in/shmulikwillinger

string

The contact’s email address.Example: gal.ashkelon@lusha.com

string

First name. Requires lastName and either companyName or companyDomain.Example: Orit

string

Last name. Requires firstName and either companyName or companyDomain.Example: Shilvock

string

The contact’s current company name.Example: Lusha

string

The contact’s current company domain.Example: lusha.com

object

Show options fields

boolean

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

object

Narrow results to contacts with recent activity, such as a promotion or job change.

Show signals fields

string[]

required

Signal types to match.Allowed values: allSignals, promotion, companyChange

string

Earliest signal date, in YYYY-MM-DD format.Example: 2025-01-01

integer

Maximum results to return per signal type. Range: 1–100.Example: 10

Response

string

Unique ID for this request, in UUID format.

object[]

One entry per contact you searched for.

Show result fields

string

Echoes the clientReferenceId you sent for this contact.

string

The Lusha contact ID. Pass this to Enrich Contacts to reveal emails and phones.

string

First name.

string

Last name.

object

Show properties

string

Current job title. Example: Vice President of Partnerships

string[]

Departments. Example: ["Business Development"]

string

Seniority level. Example: Vice President

object

Show properties

string

Lusha company ID. Example: 16303253

string

Company name. Example: Lusha

string

Company domain. Example: www.lusha.com

string

Industry. Example: Technology, Information & Media

object

Show properties

string

Example: Israel

string

Example: Tel Aviv District

string

Example: Tel Aviv

Show properties

string

LinkedIn profile URL.

string[]

Data points already available on this profile. Example: ["firstName", "lastName", "jobTitle", "location", "socialLinks", "emails"]

object[]

What you can unlock via Enrich Contacts, and its credit cost.

Show properties

string

emails or phones.

integer

Credit cost. 0 if already revealed for your account.

string[]

Signal types detected for this contact, when a signals filter was applied. Example: ["promotion", "companyChange"]

object

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

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.

Billing: Charged per successful result via the api_search action.

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 \
  --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"
      },
      {
        "clientReferenceId": "my-ref-2",
        "linkedinUrl": "https://www.linkedin.com/in/shmulikwillinger"
      },
      {
        "clientReferenceId": "my-ref-3",
        "email": "gal.ashkelon@lusha.com"
      },
      {
        "clientReferenceId": "my-ref-4",
        "id": "12345"
      }
    ],
    "options": {
      "includePartialProfiles": true
    }
  }'

{
  "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"
    },
    {
      "clientReferenceId": "my-ref-3",
      "email": "gal.ashkelon@lusha.com"
    },
    {
      "clientReferenceId": "my-ref-4",
      "id": "12345"
    }
  ],
  "options": {
    "includePartialProfiles": true
  }
}

Example response

{
  "requestId": "6e4b1192-9440-42c4-9a3e-793ddef6d73c",
  "results": [
    {
      "clientReferenceId": "my-ref-1",
      "id": "4415824633",
      "firstName": "Orit",
      "lastName": "Shilvock",
      "jobTitle": {
        "title": "Vice President of Partnerships",
        "departments": ["Business Development"],
        "seniority": "Vice President"
      },
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com",
        "industry": "Technology, Information & Media"
      },
      "location": {
        "country": "Israel",
        "city": "Tel Aviv"
      },
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/orit-shilvock-6243bb5"
      },
      "has": ["firstName", "lastName", "jobTitle", "location", "socialLinks", "emails"],
      "canReveal": [
        { "field": "emails", "credits": 1 }
      ]
    },
    {
      "clientReferenceId": "my-ref-4",
      "error": {
        "code": "NOT_FOUND",
        "message": "Contact not found"
      }
    }
  ],
  "billing": {
    "creditsCharged": 1,
    "resultsReturned": 3
  }
}

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

options

object

Additional options for search requests

Show child attributes

signals

object

Show child attributes

Response

Successful response

requestId

string<uuid>

Example:

"3c7f6d96-4a72-40cd-96c1-2efcfabeb727"

results

object[]

Show child attributes

billing

object

Credit usage summary for a V3 API request

Show child attributes

⌘I

Search Contacts

curl --request POST \
  --url https://api.lusha.com/v3/contacts/search \
  --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"
    },
    {
      "clientReferenceId": "my-ref-3",
      "email": "gal.ashkelon@lusha.com"
    },
    {
      "clientReferenceId": "my-ref-4",
      "id": "12345"
    }
  ],
  "options": {
    "includePartialProfiles": true
  }
}
'

import requests

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

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"
        },
        {
            "clientReferenceId": "my-ref-3",
            "email": "gal.ashkelon@lusha.com"
        },
        {
            "clientReferenceId": "my-ref-4",
            "id": "12345"
        }
    ],
    "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'
      },
      {clientReferenceId: 'my-ref-3', email: 'gal.ashkelon@lusha.com'},
      {clientReferenceId: 'my-ref-4', id: '12345'}
    ],
    options: {includePartialProfiles: true}
  })
};

fetch('https://api.lusha.com/v3/contacts/search', 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")
  .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      \"clientReferenceId\": \"my-ref-3\",\n      \"email\": \"gal.ashkelon@lusha.com\"\n    },\n    {\n      \"clientReferenceId\": \"my-ref-4\",\n      \"id\": \"12345\"\n    }\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"

	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      \"clientReferenceId\": \"my-ref-3\",\n      \"email\": \"gal.ashkelon@lusha.com\"\n    },\n    {\n      \"clientReferenceId\": \"my-ref-4\",\n      \"id\": \"12345\"\n    }\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": "6e4b1192-9440-42c4-9a3e-793ddef6d73c",
  "results": [
    {
      "clientReferenceId": "my-ref-1",
      "id": "4415824633",
      "firstName": "Orit",
      "lastName": "Shilvock",
      "jobTitle": {
        "title": "Vice President of Partnerships",
        "departments": [
          "Business Development"
        ],
        "seniority": "Vice President"
      },
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com",
        "industry": "Technology, Information & Media"
      },
      "location": {
        "country": "Israel",
        "city": "Tel Aviv"
      },
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/orit-shilvock-6243bb5"
      },
      "has": [
        "firstName",
        "lastName",
        "jobTitle",
        "location",
        "socialLinks",
        "emails"
      ],
      "canReveal": [
        {
          "field": "emails",
          "credits": 1
        }
      ]
    },
    {
      "clientReferenceId": "my-ref-2",
      "id": "4415824679",
      "firstName": "Shmulik",
      "lastName": "Willinger",
      "jobTitle": {
        "title": "Chief Architect",
        "departments": [
          "Engineering & Technical"
        ],
        "seniority": "C-Suite"
      },
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com",
        "industry": "Technology, Information & Media"
      },
      "location": {
        "country": "Israel",
        "city": "Tel Aviv"
      },
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/shmulikwillinger"
      },
      "has": [
        "firstName",
        "lastName",
        "jobTitle",
        "location",
        "socialLinks",
        "emails"
      ],
      "canReveal": [
        {
          "field": "emails",
          "credits": 1
        }
      ]
    },
    {
      "clientReferenceId": "my-ref-3",
      "id": "4415824664",
      "firstName": "Gal",
      "lastName": "Ashkelon",
      "jobTitle": {
        "title": "Global Partner Program Manager",
        "departments": [
          "Business Development"
        ],
        "seniority": "Manager"
      },
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com",
        "industry": "Technology, Information & Media"
      },
      "location": {
        "country": "Israel",
        "city": "Tel Aviv"
      },
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/gal-ashkelon-39408557"
      },
      "has": [
        "firstName",
        "lastName",
        "jobTitle",
        "location",
        "socialLinks",
        "emails"
      ],
      "canReveal": [
        {
          "field": "emails",
          "credits": 1
        }
      ]
    },
    {
      "clientReferenceId": "my-ref-4",
      "error": {
        "code": "NOT_FOUND",
        "message": "Contact not found"
      }
    }
  ],
  "billing": {
    "creditsCharged": 1,
    "resultsReturned": 3
  }
}

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