Contact Recommendations
Returns the recommended contacts for the calling user, ranked by Lusha against your Target Profiles and recent signals.
Each result is a contact preview (name, job title, company, location, LinkedIn URL) plus a recommendation block with the lead score, ICP fit score, signal score, and the Target Profiles it matches. All scores are between 0 and 1. Emails and phones are not included. Pass the returned id to Enrich Contacts to reveal them.
Filtering: Get valid targetIcp ids and signals names from Contact Recommendation Filters. Values within the same filter are OR-ed.
Sorting: Up to 4 sort entries from leadScore, signalScore, icpFitScore, and targetIcp, applied in order. All entries must use the same order; mixing asc and desc returns 400. The default is leadScore descending.
Pagination: page is 0-based (0-1000), size is 10-100. The defaults are page: 0 and size: 25. An empty body {} returns the first 25 recommendations.
Access: Requires a user-scoped identity, either OAuth or an API key owned by a team member. Account-wide API keys return
403.
Billing: Charged per result without an
error, via thecontactRecommendationsRevealaction. Results with anerror(e.g.COMPLIANCE_RESTRICTED) keep their scores but carry no personal data and are not charged.
curl --request POST \
--url https://api.lusha.com/v3/contacts/recommendations \
--header 'Content-Type: application/json' \
--header 'api_key: <api-key>' \
--data '{}'{
"requestId": "145fc2e1-bd6c-4618-a0c7-e1c7fa4eb6a7",
"userRecommendationsId": "1b403dbc-34fc-5dcc-8a4c-aea3db5b6288",
"results": [
{
"id": "v1.aBcDeFgHiJkLmNoPqRsTuV",
"firstName": "Jane",
"lastName": "Doe",
"jobTitle": {
"title": "Senior DevOps Engineer",
"departments": [
"Engineering & Technical"
],
"seniority": "Senior"
},
"company": {
"id": "v1.zYxWvUtSrQpOnMlKjIhG",
"name": "Example Corp",
"domain": "example.com",
"industry": "Technology, Information & Media"
},
"location": {
"country": "United Kingdom"
},
"socialLinks": {
"linkedin": "https://www.linkedin.com/in/jane-doe-example"
},
"has": [
"firstName",
"lastName",
"jobTitle",
"location",
"socialLinks",
"emails",
"phones"
],
"canReveal": [
{
"field": "emails",
"credits": 1
},
{
"field": "phones",
"credits": 5
}
],
"signalTypes": [
"promotion",
"surgeInHiring"
],
"recommendation": {
"leadScore": 0.95,
"icpFitScore": 0.84,
"signalScore": 0.64,
"targetIcp": [
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "Lusha Calculated Target Profile"
}
]
}
}
],
"pagination": {
"page": 0,
"size": 25,
"total": 603
},
"billing": {
"creditsCharged": 1,
"resultsReturned": 1
}
}{
"statusCode": 400,
"message": "Invalid request parameters"
}{
"statusCode": 401,
"message": "Invalid API key"
}{
"statusCode": 402,
"message": "Insufficient credits for this operation"
}{
"statusCode": 403,
"message": "This endpoint requires a user-scoped identity. Use OAuth, or a member-owned API key. Account-wide API keys are not supported."
}{
"statusCode": 429,
"message": "Too many requests. Please wait before making another request."
}{
"statusCode": 500,
"message": "Internal server error. Please try again later."
}{
"statusCode": 503,
"message": "Failed to fetch unified contact recommendations"
}Authorizations
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
All fields are optional. An empty body returns the first page sorted by leadScore descending.
Response
Successfully retrieved contact recommendations
Request id for support and tracing
Stable id of the user's current recommendation set. Use it to cache or dedupe results across pages.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Credit usage summary for a V3 API request
Show child attributes
Show child attributes
Recommendation list ids behind this page. Omitted when empty.
Was this page helpful?
curl --request POST \
--url https://api.lusha.com/v3/contacts/recommendations \
--header 'Content-Type: application/json' \
--header 'api_key: <api-key>' \
--data '{}'{
"requestId": "145fc2e1-bd6c-4618-a0c7-e1c7fa4eb6a7",
"userRecommendationsId": "1b403dbc-34fc-5dcc-8a4c-aea3db5b6288",
"results": [
{
"id": "v1.aBcDeFgHiJkLmNoPqRsTuV",
"firstName": "Jane",
"lastName": "Doe",
"jobTitle": {
"title": "Senior DevOps Engineer",
"departments": [
"Engineering & Technical"
],
"seniority": "Senior"
},
"company": {
"id": "v1.zYxWvUtSrQpOnMlKjIhG",
"name": "Example Corp",
"domain": "example.com",
"industry": "Technology, Information & Media"
},
"location": {
"country": "United Kingdom"
},
"socialLinks": {
"linkedin": "https://www.linkedin.com/in/jane-doe-example"
},
"has": [
"firstName",
"lastName",
"jobTitle",
"location",
"socialLinks",
"emails",
"phones"
],
"canReveal": [
{
"field": "emails",
"credits": 1
},
{
"field": "phones",
"credits": 5
}
],
"signalTypes": [
"promotion",
"surgeInHiring"
],
"recommendation": {
"leadScore": 0.95,
"icpFitScore": 0.84,
"signalScore": 0.64,
"targetIcp": [
{
"id": "00000000-0000-0000-0000-000000000000",
"name": "Lusha Calculated Target Profile"
}
]
}
}
],
"pagination": {
"page": 0,
"size": 25,
"total": 603
},
"billing": {
"creditsCharged": 1,
"resultsReturned": 1
}
}{
"statusCode": 400,
"message": "Invalid request parameters"
}{
"statusCode": 401,
"message": "Invalid API key"
}{
"statusCode": 402,
"message": "Insufficient credits for this operation"
}{
"statusCode": 403,
"message": "This endpoint requires a user-scoped identity. Use OAuth, or a member-owned API key. Account-wide API keys are not supported."
}{
"statusCode": 429,
"message": "Too many requests. Please wait before making another request."
}{
"statusCode": 500,
"message": "Internal server error. Please try again later."
}{
"statusCode": 503,
"message": "Failed to fetch unified contact recommendations"
}