# Contact Lookalikes

Returns contact lookalikes based on seed contacts.

Endpoint: (POST) https://api.lusha.com/v3/lookalike/contacts


  #### How It Works


First Request (Start a New Run):
- Do not send dedupeSessionId
- Server generates one and returns it in the response
- Use returned dedupeSessionId for subsequent "get more" requests

Subsequent Requests ("Get More"):
- Send the returned dedupeSessionId to fetch more results without duplicates
- Server dedupes against all contacts previously returned for the dedupeSessionId
- User-provided exclude.* is applied on every request and combined with server-side dedupe
- Session history retained for 30 days from last activity (sliding window)
---

Endpoint: POST /v3/lookalike/contacts
Security: ApiKeyAuth

## Request fields (application/json):

  - `dedupeSessionId` (string)
    Dedupe session identifier. Omit on the first request to start a new run (server generates one). Provide on subsequent requests to get more results without duplicates.
    Example: "58adaa77-7a6e-4c9b-8c2d-820a6538e613"

  - `seeds` (object,null, required)
    Identifier batch for contact inputs. Provide at least one of linkedinUrls, contacts, emails, or contactIds. For seeds: total unique identifiers across all arrays must be 5-100. For exclude: total must be at most 500.

  - `seeds.linkedinUrls` (array)
    Example: ["https://www.linkedin.com/in/johndoe"]

  - `seeds.contacts` (array)

  - `seeds.contacts.firstName` (string, required)
    First name
    Example: "John"

  - `seeds.contacts.lastName` (string, required)
    Last name
    Example: "Doe"

  - `seeds.contacts.companyDomain` (string)
    Company domain (e.g., acme.com)
    Example: "acme.com"

  - `seeds.contacts.companyName` (string)
    Company name (alternative to companyDomain)
    Example: "Acme Inc"

  - `seeds.emails` (array)
    Example: ["john@acme.com"]

  - `seeds.contactIds` (array)
    Example: [1234,4567]

  - `exclude` (object,null)
    Identifier batch for contact inputs. Provide at least one of linkedinUrls, contacts, emails, or contactIds. For seeds: total unique identifiers across all arrays must be 5-100. For exclude: total must be at most 500.

  - `limit` (integer)
    Number of results to return per call (1-100)
    Example: 25

## Response 200 fields (application/json):

  - `dedupeSessionId` (string,null, required)
    Server-generated session id to use for subsequent "get more" requests. Null when no results on first request.
    Example: "58adaa77-7a6e-4c9b-8c2d-820a6538e613"

  - `results` (array, required)
    Lookalike contacts

  - `results.id` (string)
    Lusha person ID
    Example: "9659196"

  - `results.firstName` (string,null)
    First name
    Example: "Sarah"

  - `results.lastName` (string,null)
    Last name
    Example: "Johnson"

  - `results.socialLinks` (object)

  - `results.socialLinks.linkedin` (string,null)
    LinkedIn profile URL
    Example: "https://www.linkedin.com/in/sarahjohnson"

  - `results.company` (object)

  - `results.company.id` (string)
    Company ID
    Example: "8605368"

  - `results.company.name` (string,null)
    Company name
    Example: "Marriott International"

  - `results.company.domain` (string,null)
    Company domain
    Example: "marriott.com"

  - `results.jobTitle` (object)

  - `results.jobTitle.title` (string,null)
    Job title
    Example: "VP of Sales"

  - `results.jobTitle.departments` (array)
    Departments
    Example: ["Sales"]

  - `results.jobTitle.seniority` (string,null)
    Seniority level
    Example: "Director"

  - `results.location` (object)

  - `results.location.country` (string,null)
    Example: "United States"

  - `results.location.state` (string,null)
    Example: "Maryland"

  - `results.location.city` (string,null)
    Example: "Bethesda"

  - `meta` (object, required)

  - `meta.returned` (integer, required)
    Number of results returned in this response
    Example: 25

  - `meta.hasMore` (boolean, required)
    Indicates whether more results are available for the same seeds + dedupeSessionId
    Example: true

  - `creditsCharged` (integer)
    Number of credits charged for this request
    Example: 3

## Response 400 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 403 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]

## Response 410 fields (application/json):

  - `code` (string, required)
    Example: "DEDUPE_SESSION_INVALID"

  - `message` (string, required)
    Example: "The provided dedupeSessionId is invalid or expired. Generate a new request without dedupeSessionId to start a fresh run."

## Response 500 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]


## Response 402 fields