> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusha.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Find similar contacts with POST /v3/contacts/lookalike

> Discover new contacts who match your best prospects by submitting seed contact identifiers, LinkedIn URLs, or emails to the Lusha contact lookalikes endpoint.

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.

<Steps>
  <Step title="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.

    ```json theme={null}
    {
      "seeds": {
        "ids": ["1234"]
      }
    }
    ```
  </Step>

  <Step title="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.

    ```json theme={null}
    {
      "dedupeSessionId": "58adaa77-7a6e-4c9b-8c2d-820a6538e613",
      "seeds": {
        "linkedinUrls": ["https://www.linkedin.com/in/shmulikwillinger"]
      }
    }
    ```
  </Step>
</Steps>

<Note>
  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.
</Note>

## Example: first request

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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](/api-reference/enrich/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.

```json theme={null}
{
  "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.

<Tip>
  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.
</Tip>

See the [full API reference](/api-reference/lookalikes/contact-lookalikes) for request/response schemas and error codes.