Contact Lookalikes

POST

contacts

lookalike

curl --request POST \
  --url https://api.lusha.com/v3/contacts/lookalike \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "seeds": {
    "linkedinUrls": [
      "https://www.linkedin.com/in/orit-shilvock-6243bb5",
      "https://www.linkedin.com/in/shmulikwillinger"
    ],
    "emails": [
      "gal.ashkelon@lusha.com",
      "miri.tamir@lusha.com"
    ],
    "ids": [
      "1234",
      "4567"
    ]
  },
  "exclude": {
    "emails": [
      "existing@customer.com"
    ]
  },
  "limit": 25
}
'

{
  "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
  "results": [
    {
      "id": "4389064624",
      "firstName": "Yehuda",
      "lastName": "Rapp",
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/yehuda-rapp-53909b99"
      },
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com"
      },
      "jobTitle": {
        "title": "Senior Solutions Engineer",
        "departments": ["Engineering & Technical"],
        "seniority": "Senior"
      },
      "location": {
        "country": "Israel",
        "state": "Tel Aviv District",
        "city": "Tel Aviv"
      }
    }
  ],
  "meta": {
    "returned": 1,
    "hasMore": true
  },
  "billing": {
    "creditsCharged": 1,
    "resultsReturned": 1
  }
}

{
  "code": "DEDUPE_SESSION_INVALID",
  "message": "The provided dedupeSessionId is invalid or expired. Generate a new request without dedupeSessionId to start a fresh run."
}

Contact Lookalikes finds contacts similar to a set of seed contacts using AI-powered recommendations. Provide 5–100 seed contacts via LinkedIn URLs, emails, Lusha IDs, or name + company, and the API returns contacts who share similar roles, seniority, and company profiles.

Endpoint

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

Authentication: API key (api_key header)

Pagination without duplicates

On your first request, omit dedupeSessionId - the server generates one and returns it. Pass it on every subsequent request to get more results without repeating contacts already seen. Sessions are retained for 30 days.

Request body

object

required

Seed contacts to match against.

Show seeds fields

string[]

LinkedIn profile URLs. Max 100 items. Example: "https://www.linkedin.com/in/orit-shilvock-6243bb5"

string[]

Email addresses. Max 100 items. Example: "gal.ashkelon@lusha.com"

string[]

Lusha contact IDs, as strings. Preferred over contactIds. Max 100 items. Example: ["1234", "4567"]

integer[]

Lusha contact IDs, as numbers. Legacy - prefer ids. Max 100 items. Example: [1234, 4567]

object[]

Seed contacts identified by name and company. Max 100 items.

Show contact object fields

string

required

Example: "Miri"

string

required

Example: "Tamir"

string

At least one of companyDomain or companyName is required. Example: "lusha.com"

string

Example: "Lusha"

string

Session ID returned from a previous call. Omit on the first request; include on every “get more” request.

object

Contacts to exclude from results, in the same shape as seeds (linkedinUrls, emails, ids, contactIds, contacts).

integer

default:"25"

Results to return per call. Range: 1–100.

Example requests

curl --request POST \
  --url https://api.lusha.com/v3/contacts/lookalike \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "seeds": {
      "linkedinUrls": ["https://www.linkedin.com/in/orit-shilvock-6243bb5"],
      "emails": ["gal.ashkelon@lusha.com"],
      "ids": ["1234"]
    },
    "exclude": {
      "emails": ["existing@customer.com"]
    },
    "limit": 25
  }'

curl --request POST \
  --url https://api.lusha.com/v3/contacts/lookalike \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
    "seeds": {
      "linkedinUrls": ["https://www.linkedin.com/in/shmulikwillinger"]
    },
    "limit": 25
  }'

Response

200 - Success

string

Session ID to use for subsequent “get more” requests. Can be null when there are no results on the first request.

object[]

Array of lookalike contacts.

Show result fields

string

Lusha contact ID. Example: "4389064624"

string

linkedin profile URL.

object

id, name, and domain of the contact’s current company.

object

title, departments, and seniority.

object

country, state, and city.

object

required

returned (results in this response) and hasMore (whether more results are available for this dedupeSessionId).

object

creditsCharged and resultsReturned for this request.

Billing: Charged per result via the lookalikeContact action.

Results are lightweight previews. Pass each id to Enrich Contacts to reveal emails and phone numbers.

Error codes

Status	Meaning
`400`	Bad request - invalid input data.
`402`	Insufficient credits.
`403`	Forbidden - account inactive, or V3 access not enabled.
`410`	`dedupeSessionId` is invalid or expired - start a new run by omitting it.
`500`	Internal server error.

{
  "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
  "results": [
    {
      "id": "4389064624",
      "firstName": "Yehuda",
      "lastName": "Rapp",
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/yehuda-rapp-53909b99"
      },
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com"
      },
      "jobTitle": {
        "title": "Senior Solutions Engineer",
        "departments": ["Engineering & Technical"],
        "seniority": "Senior"
      },
      "location": {
        "country": "Israel",
        "state": "Tel Aviv District",
        "city": "Tel Aviv"
      }
    }
  ],
  "meta": {
    "returned": 1,
    "hasMore": true
  },
  "billing": {
    "creditsCharged": 1,
    "resultsReturned": 1
  }
}

{
  "code": "DEDUPE_SESSION_INVALID",
  "message": "The provided dedupeSessionId is invalid or expired. Generate a new request without dedupeSessionId to start a fresh run."
}

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

seeds

object

required

Required. Minimum 5, maximum 100 seed contacts in total, counted across all identifier types combined (linkedinUrls + emails + ids + contactIds + contacts). Fewer than 5 total seeds is rejected with 400. Cannot be null.

Show child attributes

dedupeSessionId

string<uuid>

Example:

"58adaa77-7a6e-4c9b-8c2d-820a6538e613"

exclude

object

Optional. Contacts to always filter out of the results (for example, existing customers). Omit the field entirely if you have nothing to exclude. Subject to the same 100-per-identifier-type cap as seeds, but has no minimum.

Show child attributes

limit

integer

default:25

Required range: 1 <= x <= 100

Example:

25

tableId

string

Optional. If provided, results are also persisted to this table. See the Tables API.

Example:

"482910"

Response

Successfully retrieved contact lookalikes

dedupeSessionId

string<uuid> | null

required

Example:

"58adaa77-7a6e-4c9b-8c2d-820a6538e613"

results

object[]

required

Show child attributes

meta

object

required

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

⌘I

curl --request POST \
  --url https://api.lusha.com/v3/contacts/lookalike \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "seeds": {
    "linkedinUrls": [
      "https://www.linkedin.com/in/orit-shilvock-6243bb5",
      "https://www.linkedin.com/in/shmulikwillinger"
    ],
    "emails": [
      "gal.ashkelon@lusha.com",
      "miri.tamir@lusha.com"
    ],
    "ids": [
      "1234",
      "4567"
    ]
  },
  "exclude": {
    "emails": [
      "existing@customer.com"
    ]
  },
  "limit": 25
}
'

{
  "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
  "results": [
    {
      "id": "4389064624",
      "firstName": "Yehuda",
      "lastName": "Rapp",
      "socialLinks": {
        "linkedin": "https://www.linkedin.com/in/yehuda-rapp-53909b99"
      },
      "company": {
        "id": "16303253",
        "name": "Lusha",
        "domain": "www.lusha.com"
      },
      "jobTitle": {
        "title": "Senior Solutions Engineer",
        "departments": ["Engineering & Technical"],
        "seniority": "Senior"
      },
      "location": {
        "country": "Israel",
        "state": "Tel Aviv District",
        "city": "Tel Aviv"
      }
    }
  ],
  "meta": {
    "returned": 1,
    "hasMore": true
  },
  "billing": {
    "creditsCharged": 1,
    "resultsReturned": 1
  }
}

{
  "code": "DEDUPE_SESSION_INVALID",
  "message": "The provided dedupeSessionId is invalid or expired. Generate a new request without dedupeSessionId to start a fresh run."
}

Overview

Resources

Endpoints

Endpoint

Request body

Example requests

Response

200 - Success

Error codes

Authorizations

Body

Response

​Endpoint

​Pagination without duplicates

​Request body

​Example requests

​Response

​200 - Success

​Error codes

Authorizations

Body

Response

Endpoint

Pagination without duplicates

Request body

Example requests

Response

200 - Success

Error codes