Prospecting Contacts

POST

contacts

prospecting

curl --request POST \
  --url https://api.lusha.com/v3/contacts/prospecting \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "pagination": {
    "page": 0,
    "size": 100
  },
  "filters": {
    "contacts": {
      "include": {
        "departments": [
          "Sales"
        ],
        "locations": [
          {
            "country": "United States"
          }
        ],
        "existingDataPoints": [
          "work_email"
        ]
      }
    },
    "companies": {
      "include": {
        "locations": [
          {
            "country": "United States"
          }
        ],
        "foundedYear": [
          {
            "min": 2000
          }
        ],
        "businessModel": [
          "B2B"
        ],
        "companyType": [
          "Public Company"
        ],
        "linkedinUrls": [
          "https://www.linkedin.com/company/google"
        ],
        "keywords": [
          "fintech"
        ]
      },
      "exclude": {
        "domains": [
          "competitor.com"
        ],
        "companyType": [
          "Self Employed"
        ]
      }
    }
  },
  "tableId": "482910",
  "options": {
    "includePartialProfiles": true,
    "excludeDnc": false,
    "maxContactsPerCompany": 2
  }
}
'

import requests

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

payload = {
    "pagination": {
        "page": 0,
        "size": 100
    },
    "filters": {
        "contacts": { "include": {
                "departments": ["Sales"],
                "locations": [{ "country": "United States" }],
                "existingDataPoints": ["work_email"]
            } },
        "companies": {
            "include": {
                "locations": [{ "country": "United States" }],
                "foundedYear": [{ "min": 2000 }],
                "businessModel": ["B2B"],
                "companyType": ["Public Company"],
                "linkedinUrls": ["https://www.linkedin.com/company/google"],
                "keywords": ["fintech"]
            },
            "exclude": {
                "domains": ["competitor.com"],
                "companyType": ["Self Employed"]
            }
        }
    },
    "tableId": "482910",
    "options": {
        "includePartialProfiles": True,
        "excludeDnc": False,
        "maxContactsPerCompany": 2
    }
}
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({
    pagination: {page: 0, size: 100},
    filters: {
      contacts: {
        include: {
          departments: ['Sales'],
          locations: [{country: 'United States'}],
          existingDataPoints: ['work_email']
        }
      },
      companies: {
        include: {
          locations: [{country: 'United States'}],
          foundedYear: [{min: 2000}],
          businessModel: ['B2B'],
          companyType: ['Public Company'],
          linkedinUrls: ['https://www.linkedin.com/company/google'],
          keywords: ['fintech']
        },
        exclude: {domains: ['competitor.com'], companyType: ['Self Employed']}
      }
    },
    tableId: '482910',
    options: {includePartialProfiles: true, excludeDnc: false, maxContactsPerCompany: 2}
  })
};

fetch('https://api.lusha.com/v3/contacts/prospecting', 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/prospecting")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"pagination\": {\n    \"page\": 0,\n    \"size\": 100\n  },\n  \"filters\": {\n    \"contacts\": {\n      \"include\": {\n        \"departments\": [\n          \"Sales\"\n        ],\n        \"locations\": [\n          {\n            \"country\": \"United States\"\n          }\n        ],\n        \"existingDataPoints\": [\n          \"work_email\"\n        ]\n      }\n    },\n    \"companies\": {\n      \"include\": {\n        \"locations\": [\n          {\n            \"country\": \"United States\"\n          }\n        ],\n        \"foundedYear\": [\n          {\n            \"min\": 2000\n          }\n        ],\n        \"businessModel\": [\n          \"B2B\"\n        ],\n        \"companyType\": [\n          \"Public Company\"\n        ],\n        \"linkedinUrls\": [\n          \"https://www.linkedin.com/company/google\"\n        ],\n        \"keywords\": [\n          \"fintech\"\n        ]\n      },\n      \"exclude\": {\n        \"domains\": [\n          \"competitor.com\"\n        ],\n        \"companyType\": [\n          \"Self Employed\"\n        ]\n      }\n    }\n  },\n  \"tableId\": \"482910\",\n  \"options\": {\n    \"includePartialProfiles\": true,\n    \"excludeDnc\": false,\n    \"maxContactsPerCompany\": 2\n  }\n}")
  .asString();

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"pagination\": {\n    \"page\": 0,\n    \"size\": 100\n  },\n  \"filters\": {\n    \"contacts\": {\n      \"include\": {\n        \"departments\": [\n          \"Sales\"\n        ],\n        \"locations\": [\n          {\n            \"country\": \"United States\"\n          }\n        ],\n        \"existingDataPoints\": [\n          \"work_email\"\n        ]\n      }\n    },\n    \"companies\": {\n      \"include\": {\n        \"locations\": [\n          {\n            \"country\": \"United States\"\n          }\n        ],\n        \"foundedYear\": [\n          {\n            \"min\": 2000\n          }\n        ],\n        \"businessModel\": [\n          \"B2B\"\n        ],\n        \"companyType\": [\n          \"Public Company\"\n        ],\n        \"linkedinUrls\": [\n          \"https://www.linkedin.com/company/google\"\n        ],\n        \"keywords\": [\n          \"fintech\"\n        ]\n      },\n      \"exclude\": {\n        \"domains\": [\n          \"competitor.com\"\n        ],\n        \"companyType\": [\n          \"Self Employed\"\n        ]\n      }\n    }\n  },\n  \"tableId\": \"482910\",\n  \"options\": {\n    \"includePartialProfiles\": true,\n    \"excludeDnc\": false,\n    \"maxContactsPerCompany\": 2\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": "fa828378-7a8e-4e5d-9f72-0270e7f7ab51",
  "pagination": { "page": 0, "size": 50, "total": 670550 },
  "results": [
    {
      "id": "670138733",
      "firstName": "Ting",
      "lastName": "Tsou"
    }
  ],
  "billing": {
    "creditsCharged": 2,
    "resultsReturned": 50
  }
}

{
  "statusCode": 400,
  "message": "Invalid request parameters"
}

{
  "statusCode": 402,
  "message": "Insufficient credits for this operation"
}

{
  "statusCode": 403,
  "message": "V3 API access is not enabled for your account"
}

Prospecting Contacts searches Lusha’s contact database for people who match your Ideal Customer Profile. Filter on contact attributes (title, seniority, department, location, existing data points, signals) and on attributes of the contact’s current company (size, revenue, industry, technologies, intent) in a single request. The response is a page of lightweight contact previews - not full records. Each preview includes an id. Pass that id to Enrich Contacts to reveal emails, phone numbers, and the rest of the contact’s data.

Prospect, then enrich

Step	Endpoint	Purpose
1	POST /v3/contacts/prospecting	Find contacts matching your ICP filters; get back previews + `id`s
2	POST /v3/contacts/enrich	Pass the `id`s from step 1 to reveal full contact data

Endpoint

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

Authentication: API key (api_key header) Results are paginated up to 50,000 total (1,000 pages × 50 results per page).

Request body

object

required

Pagination controls.

Show pagination fields

integer

default:"0"

Page number. Range: 0–1000.

integer

default:"25"

Results per page. Range: 10–100.

object

required

The top-level filter container. Provide at least one of contacts or companies.

Show filters.contacts

object

Criteria that matching contacts must satisfy.

Show include fields

string[]

Full names to match.

string[]

Free-text job titles to match. Example: ["VP Sales", "Director of Sales"]

string[]

Job titles that must match exactly, rather than fuzzy-matching.

string[]

Normalized/canonical job title values.

string

Free-text search across contact fields. Max length: 200.

string[]

Country codes. Example: ["US", "CA"]

object[]

Geographic filters. Each object may include city, state, country, continent, and countryGrouping. Example: [{ "country": "United States" }]

integer[]

Seniority level IDs. Example: [4, 5]

string[]

Department names. Example: ["Sales", "Engineering"]

string[]

Match specific LinkedIn profile URLs.

string[]

Only return contacts that already have specific data available. Example: ["work_email", "work_phone"]

object

Filter contacts that have a signal of the specified types.

Show signals fields

string[]

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

string

Earliest signal date, in YYYY-MM-DD format.

object

Same fields as include. Contacts matching this criteria are removed from results.

Show filters.companies

object

Criteria that the contact’s current company must satisfy.

Show include fields

string[]

Company names to include.

string[]

Company domains to include. Example: ["lusha.com"]

string[]

Lusha company IDs to include.

object[]

Geographic filters. Example: [{ "country": "United States" }]

object[]

Employee count ranges as { "min": ..., "max": ... }. Example: [{ "min": 50, "max": 500 }]

object[]

Revenue ranges as { "min": ..., "max": ... }.

string[]

Technologies the company uses. Example: ["Salesforce", "HubSpot"]

string

"or" or "and" - how the technologies list is combined.

string[]

Industry labels. Example: ["Software", "SaaS"]

integer[]

Main industry IDs.

integer[]

Sub-industry IDs.

string[]

Buyer intent topics. Example: ["Cloud Migration"]

string

"or" or "and" - how the intentTopics list is combined.

object[]

Ranges ({ "min": ..., "max": ... }) on the number of matched intent topics.

string[]

SIC industry classification codes.

string[]

NAICS industry classification codes.

object

Funding filters.

Show funding fields

boolean

Filter for companies that have IPO’d.

object[]

Funding amount ranges as { "min": ..., "max": ... }.

string[]

Funding round types. Example: ["Series B", "Series C"]

string[]

Named investors.

object[]

Founding year ranges as { "min": ..., "max": ... }.

string[]

Allowed values: B2B, B2C, B2G.

string[]

Allowed values: Government, Private Company, Public Company, Educational, Non Profit, Self Employed.

string[]

Company LinkedIn URLs. Example: ["https://www.linkedin.com/company/microsoft"]

string[]

Free-text keywords. Example: ["cloud", "artificial intelligence"]

object

Same fields as include. Companies matching this criteria are removed from results.

object

Show options fields

boolean

default:"true"

When true, includes contacts with incomplete data in results.

boolean

When true, excludes contacts whose phone numbers are all marked Do Not Call.

Use the Contact filter types and Contact filter values endpoints to look up valid values (departments, seniority IDs, existing data points, and more) before building a request.

Example request

curl --request POST \
  --url https://api.lusha.com/v3/contacts/prospecting \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "pagination": { "page": 0, "size": 50 },
    "filters": {
      "contacts": {
        "include": {
          "departments": ["Sales"],
          "locations": [{ "country": "United States" }],
          "existingDataPoints": ["work_email"]
        }
      },
      "companies": {
        "include": {
          "locations": [{ "country": "United States" }],
          "businessModel": ["B2B"],
          "companyType": ["Public Company"]
        }
      }
    },
    "options": {
      "includePartialProfiles": true,
      "excludeDnc": false
    }
  }'

{
  "pagination": { "page": 0, "size": 50 },
  "filters": {
    "contacts": {
      "include": {
        "departments": ["Sales"],
        "locations": [{ "country": "United States" }],
        "existingDataPoints": ["work_email"]
      }
    },
    "companies": {
      "include": {
        "locations": [{ "country": "United States" }],
        "businessModel": ["B2B"],
        "companyType": ["Public Company"]
      }
    }
  },
  "options": {
    "includePartialProfiles": true,
    "excludeDnc": false
  }
}

Response

200 - Success

string

Unique ID for this search.

object

page, size, and total (total matching contacts across all pages).

object[]

Array of contact previews.

Show preview fields

string

Lusha contact ID. Pass this to Enrich Contacts to reveal full data.

string

Echoes back a client-supplied reference ID, if you passed one.

string

object

title, departments, and seniority.

object

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

object

country, state, and city.

linkedin profile URL.

string[]

Fields already populated on this preview. Example: ["firstName", "lastName", "jobTitle", "location", "socialLinks", "emails"]

object[]

Fields you can reveal via Enrich Contacts, each as { "field": "emails" | "phones", "credits": <integer> }. credits is 0 when your account has already revealed that field for this contact.

string[]

Signal types detected for this contact. Present when signal filtering was requested and matched.

object

Present only when this item failed. code is one of NOT_FOUND, COMPLIANCE_RESTRICTED, ENRICH_FAILED; message explains why.

object

creditsCharged and resultsReturned for this request.

Billing: Prospecting is charged per result via the api_search action. If you filter by signals, an additional charge applies per matched signal per result.

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.

{
  "requestId": "fa828378-7a8e-4e5d-9f72-0270e7f7ab51",
  "pagination": { "page": 0, "size": 50, "total": 670550 },
  "results": [
    {
      "id": "670138733",
      "firstName": "Ting",
      "lastName": "Tsou"
    }
  ],
  "billing": {
    "creditsCharged": 2,
    "resultsReturned": 50
  }
}

{
  "statusCode": 400,
  "message": "Invalid request parameters"
}

{
  "statusCode": 402,
  "message": "Insufficient credits for this operation"
}

{
  "statusCode": 403,
  "message": "V3 API access is not enabled for your account"
}

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

pagination

object

required

Show child attributes

filters

object

required

Show child attributes

tableId

string

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

Example:

"482910"

options

object

Show child attributes

Response

Successful response

requestId

string<uuid>

results

object[]

Show child attributes

pagination

object

Pagination for Prospecting Contacts. Extends the standard pagination object with two optional fields describing the total count. Both keys are omitted when not returned.

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

Prospecting Contacts

curl --request POST \
  --url https://api.lusha.com/v3/contacts/prospecting \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "pagination": {
    "page": 0,
    "size": 100
  },
  "filters": {
    "contacts": {
      "include": {
        "departments": [
          "Sales"
        ],
        "locations": [
          {
            "country": "United States"
          }
        ],
        "existingDataPoints": [
          "work_email"
        ]
      }
    },
    "companies": {
      "include": {
        "locations": [
          {
            "country": "United States"
          }
        ],
        "foundedYear": [
          {
            "min": 2000
          }
        ],
        "businessModel": [
          "B2B"
        ],
        "companyType": [
          "Public Company"
        ],
        "linkedinUrls": [
          "https://www.linkedin.com/company/google"
        ],
        "keywords": [
          "fintech"
        ]
      },
      "exclude": {
        "domains": [
          "competitor.com"
        ],
        "companyType": [
          "Self Employed"
        ]
      }
    }
  },
  "tableId": "482910",
  "options": {
    "includePartialProfiles": true,
    "excludeDnc": false,
    "maxContactsPerCompany": 2
  }
}
'

import requests

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

payload = {
    "pagination": {
        "page": 0,
        "size": 100
    },
    "filters": {
        "contacts": { "include": {
                "departments": ["Sales"],
                "locations": [{ "country": "United States" }],
                "existingDataPoints": ["work_email"]
            } },
        "companies": {
            "include": {
                "locations": [{ "country": "United States" }],
                "foundedYear": [{ "min": 2000 }],
                "businessModel": ["B2B"],
                "companyType": ["Public Company"],
                "linkedinUrls": ["https://www.linkedin.com/company/google"],
                "keywords": ["fintech"]
            },
            "exclude": {
                "domains": ["competitor.com"],
                "companyType": ["Self Employed"]
            }
        }
    },
    "tableId": "482910",
    "options": {
        "includePartialProfiles": True,
        "excludeDnc": False,
        "maxContactsPerCompany": 2
    }
}
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({
    pagination: {page: 0, size: 100},
    filters: {
      contacts: {
        include: {
          departments: ['Sales'],
          locations: [{country: 'United States'}],
          existingDataPoints: ['work_email']
        }
      },
      companies: {
        include: {
          locations: [{country: 'United States'}],
          foundedYear: [{min: 2000}],
          businessModel: ['B2B'],
          companyType: ['Public Company'],
          linkedinUrls: ['https://www.linkedin.com/company/google'],
          keywords: ['fintech']
        },
        exclude: {domains: ['competitor.com'], companyType: ['Self Employed']}
      }
    },
    tableId: '482910',
    options: {includePartialProfiles: true, excludeDnc: false, maxContactsPerCompany: 2}
  })
};

fetch('https://api.lusha.com/v3/contacts/prospecting', 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/prospecting")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"pagination\": {\n    \"page\": 0,\n    \"size\": 100\n  },\n  \"filters\": {\n    \"contacts\": {\n      \"include\": {\n        \"departments\": [\n          \"Sales\"\n        ],\n        \"locations\": [\n          {\n            \"country\": \"United States\"\n          }\n        ],\n        \"existingDataPoints\": [\n          \"work_email\"\n        ]\n      }\n    },\n    \"companies\": {\n      \"include\": {\n        \"locations\": [\n          {\n            \"country\": \"United States\"\n          }\n        ],\n        \"foundedYear\": [\n          {\n            \"min\": 2000\n          }\n        ],\n        \"businessModel\": [\n          \"B2B\"\n        ],\n        \"companyType\": [\n          \"Public Company\"\n        ],\n        \"linkedinUrls\": [\n          \"https://www.linkedin.com/company/google\"\n        ],\n        \"keywords\": [\n          \"fintech\"\n        ]\n      },\n      \"exclude\": {\n        \"domains\": [\n          \"competitor.com\"\n        ],\n        \"companyType\": [\n          \"Self Employed\"\n        ]\n      }\n    }\n  },\n  \"tableId\": \"482910\",\n  \"options\": {\n    \"includePartialProfiles\": true,\n    \"excludeDnc\": false,\n    \"maxContactsPerCompany\": 2\n  }\n}")
  .asString();

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"pagination\": {\n    \"page\": 0,\n    \"size\": 100\n  },\n  \"filters\": {\n    \"contacts\": {\n      \"include\": {\n        \"departments\": [\n          \"Sales\"\n        ],\n        \"locations\": [\n          {\n            \"country\": \"United States\"\n          }\n        ],\n        \"existingDataPoints\": [\n          \"work_email\"\n        ]\n      }\n    },\n    \"companies\": {\n      \"include\": {\n        \"locations\": [\n          {\n            \"country\": \"United States\"\n          }\n        ],\n        \"foundedYear\": [\n          {\n            \"min\": 2000\n          }\n        ],\n        \"businessModel\": [\n          \"B2B\"\n        ],\n        \"companyType\": [\n          \"Public Company\"\n        ],\n        \"linkedinUrls\": [\n          \"https://www.linkedin.com/company/google\"\n        ],\n        \"keywords\": [\n          \"fintech\"\n        ]\n      },\n      \"exclude\": {\n        \"domains\": [\n          \"competitor.com\"\n        ],\n        \"companyType\": [\n          \"Self Employed\"\n        ]\n      }\n    }\n  },\n  \"tableId\": \"482910\",\n  \"options\": {\n    \"includePartialProfiles\": true,\n    \"excludeDnc\": false,\n    \"maxContactsPerCompany\": 2\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": "fa828378-7a8e-4e5d-9f72-0270e7f7ab51",
  "pagination": { "page": 0, "size": 50, "total": 670550 },
  "results": [
    {
      "id": "670138733",
      "firstName": "Ting",
      "lastName": "Tsou"
    }
  ],
  "billing": {
    "creditsCharged": 2,
    "resultsReturned": 50
  }
}

{
  "statusCode": 400,
  "message": "Invalid request parameters"
}

{
  "statusCode": 402,
  "message": "Insufficient credits for this operation"
}

{
  "statusCode": 403,
  "message": "V3 API access is not enabled for your account"
}

Overview

Resources

Endpoints

Endpoint

Request body

Example request

Response

200 - Success

Error codes

Authorizations

Body

Response

​Endpoint

​Request body

​Example request

​Response

​200 - Success

​Error codes

Authorizations

Body

Response

Endpoint

Request body

Example request

Response

200 - Success

Error codes