Find similar contacts with POST /v3/contacts/lookalike

The contact lookalikes endpoint takes a set of seed contacts and returns new contacts who share similar roles, seniority levels, and company profiles. Use it to expand your total addressable market or fill your pipeline with prospects who look like your highest-converting leads. Endpoint: POST https://api.lusha.com/v3/contacts/lookalike

Request body

Field	Type	Required	Description
`seeds`	object	Yes	Seed contacts, identified via `linkedinUrls`, `emails`, `ids`, `contactIds`, and/or `contacts` (name + company). Provide 5–100 unique identifiers total across these fields.
`dedupeSessionId`	string	No	Session token returned from a previous call. Omit on the first request.
`exclude`	object	No	Contacts to exclude from results, in the same shape as `seeds`. Applied on every request, combined with session-level deduplication.
`limit`	integer	No	Results per call. Range `1`–`100`, default `25`.

Each entry in seeds.contacts needs firstName, lastName, and at least one of companyDomain or companyName. Prefer ids (strings) over the legacy contactIds (numbers) when you already know a contact’s Lusha ID.

Paginating without duplicates

The endpoint uses a dedupeSessionId to track which contacts have already been returned. Follow this pattern to retrieve more results across multiple calls.

First call - no dedupeSessionId

Send your seed contacts without a dedupeSessionId. The server creates a new session and returns the first batch of lookalikes along with a dedupeSessionId you will use in the next call.

{
  "seeds": {
    "ids": ["1234"]
  }
}

Subsequent calls - pass the session ID

Include the dedupeSessionId returned in the previous response. The server skips contacts it has already returned for this session.

{
  "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
  "seeds": {
    "linkedinUrls": ["https://www.linkedin.com/in/shmulikwillinger"]
  }
}

Sessions are retained for 30 days from the last activity (sliding window). After 30 days of inactivity the session expires and the next call starts a new one.

Example: first request

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

Example: get more results

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

Example response

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

The response always includes dedupeSessionId and meta.hasMore - carry dedupeSessionId forward and check hasMore to decide whether to keep paging. Results are lightweight previews (name, current company, job title, location). Pipe each id into Enrich Contacts to retrieve emails and phone numbers.

Excluding specific contacts

Pass an exclude object - shaped like seeds - to filter out contacts you already own or do not want to see, regardless of session state. The server applies your exclusions on top of session-level deduplication on every call.

{
  "seeds": {
    "ids": ["1234"]
  },
  "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
  "exclude": {
    "ids": ["1111111111", "2222222222"]
  }
}

Use cases

Expand total addressable market - start from your top-performing contacts and discover similarly qualified prospects you have not yet reached.
Fill pipeline gaps - when a segment goes cold, use lookalikes to quickly identify new prospects with a comparable profile.

Seed the endpoint with your closed-won contacts for the best match quality. The more specific and consistent the seed set, the more relevant the lookalike results.

See the full API reference for request/response schemas and error codes.

Overview

Resources

Endpoints

Find similar contacts with POST /v3/contacts/lookalike

Request body

Paginating without duplicates

Example: first request

Example: get more results

Example response

Excluding specific contacts

Use cases

​Request body

​Paginating without duplicates

​Example: first request

​Example: get more results

​Example response

​Excluding specific contacts

​Use cases

Request body

Paginating without duplicates

Example: first request

Example: get more results

Example response

Excluding specific contacts

Use cases