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
Body
All fields are optional. An empty body returns the first page sorted by leadScore descending.
Response
Successfully retrieved contact recommendations
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"
}