Signals
Score Contacts by Signal Activity
Score contacts by their active buying signals. Returns the aggregate Signal Score - a [0, 1] value - plus the active signal breakdown per contact.
Accepts up to 100 contacts. Each contact is resolved to a Lusha person ID and company ID server-side (identity only - no PII is revealed) before scoring. Provide one of:
id(encrypted Lusha contact ID)linkedinUrlemailfirstName+lastName+ (companyNameorcompanyDomain)
Each result is one of:
- A scored entry -
signalScore,signalTypes, andnoActiveSignals. - A
NOT_FOUNDentry - identity resolution failed for the supplied identifier. - A
NO_SCOREentry - the contact resolved, but the scoring engine returned nothing for it.
Note: A full outage of the identity-resolution provider is never masked as
NOT_FOUND- it returns a retryable502instead, so callers can retry rather than treating the batch as authoritatively unresolved.
Billing: 1 credit is charged per scored row via
signal_score_contact_reveal. This action is currently limited-availability - while it isn’t yet seeded on an account’s pricebook, the endpoint stays free (billing.creditsChargedis0). Error rows (NOT_FOUND/NO_SCORE) are never charged.
POST
/
v3
/
contacts
/
signal-score
Score Contacts by Signal Activity
curl --request POST \
--url https://api.lusha.com/v3/contacts/signal-score \
--header 'Content-Type: application/json' \
--header 'api_key: <api-key>' \
--data '
{
"contacts": [
{
"clientReferenceId": "ref-1",
"id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345"
},
{
"clientReferenceId": "ref-2",
"linkedinUrl": "https://linkedin.com/in/johndoe"
},
{
"clientReferenceId": "ref-3",
"firstName": "Jane",
"lastName": "Doe",
"companyDomain": "acme.com"
}
]
}
'import requests
url = "https://api.lusha.com/v3/contacts/signal-score"
payload = { "contacts": [
{
"clientReferenceId": "ref-1",
"id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345"
},
{
"clientReferenceId": "ref-2",
"linkedinUrl": "https://linkedin.com/in/johndoe"
},
{
"clientReferenceId": "ref-3",
"firstName": "Jane",
"lastName": "Doe",
"companyDomain": "acme.com"
}
] }
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({
contacts: [
{clientReferenceId: 'ref-1', id: 'v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345'},
{clientReferenceId: 'ref-2', linkedinUrl: 'https://linkedin.com/in/johndoe'},
{
clientReferenceId: 'ref-3',
firstName: 'Jane',
lastName: 'Doe',
companyDomain: 'acme.com'
}
]
})
};
fetch('https://api.lusha.com/v3/contacts/signal-score', 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/signal-score")
.header("api_key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"contacts\": [\n {\n \"clientReferenceId\": \"ref-1\",\n \"id\": \"v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345\"\n },\n {\n \"clientReferenceId\": \"ref-2\",\n \"linkedinUrl\": \"https://linkedin.com/in/johndoe\"\n },\n {\n \"clientReferenceId\": \"ref-3\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"companyDomain\": \"acme.com\"\n }\n ]\n}")
.asString();package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.lusha.com/v3/contacts/signal-score"
payload := strings.NewReader("{\n \"contacts\": [\n {\n \"clientReferenceId\": \"ref-1\",\n \"id\": \"v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345\"\n },\n {\n \"clientReferenceId\": \"ref-2\",\n \"linkedinUrl\": \"https://linkedin.com/in/johndoe\"\n },\n {\n \"clientReferenceId\": \"ref-3\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"companyDomain\": \"acme.com\"\n }\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": "5d6f13d2-f6b0-4e55-85d5-04e17f932c1a",
"results": [
{
"clientReferenceId": "ref-1",
"id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345",
"fullName": "Jane Doe",
"company": {
"id": "v1.6789ZyXwVuTsRqPoNmLkJiHgFeDcBa01",
"name": "Acme Corp",
"domain": "acme.com"
},
"signalScore": 0.3,
"signalTypes": [
"promotion"
],
"noActiveSignals": false
},
{
"clientReferenceId": "ref-2",
"error": {
"code": "NOT_FOUND",
"message": "Contact not found"
}
}
],
"billing": {
"creditsCharged": 1,
"resultsReturned": 1
}
}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
application/json
Required array length:
1 - 100 elementsShow child attributes
Show child attributes
Was this page helpful?
⌘I
Score Contacts by Signal Activity
curl --request POST \
--url https://api.lusha.com/v3/contacts/signal-score \
--header 'Content-Type: application/json' \
--header 'api_key: <api-key>' \
--data '
{
"contacts": [
{
"clientReferenceId": "ref-1",
"id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345"
},
{
"clientReferenceId": "ref-2",
"linkedinUrl": "https://linkedin.com/in/johndoe"
},
{
"clientReferenceId": "ref-3",
"firstName": "Jane",
"lastName": "Doe",
"companyDomain": "acme.com"
}
]
}
'import requests
url = "https://api.lusha.com/v3/contacts/signal-score"
payload = { "contacts": [
{
"clientReferenceId": "ref-1",
"id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345"
},
{
"clientReferenceId": "ref-2",
"linkedinUrl": "https://linkedin.com/in/johndoe"
},
{
"clientReferenceId": "ref-3",
"firstName": "Jane",
"lastName": "Doe",
"companyDomain": "acme.com"
}
] }
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({
contacts: [
{clientReferenceId: 'ref-1', id: 'v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345'},
{clientReferenceId: 'ref-2', linkedinUrl: 'https://linkedin.com/in/johndoe'},
{
clientReferenceId: 'ref-3',
firstName: 'Jane',
lastName: 'Doe',
companyDomain: 'acme.com'
}
]
})
};
fetch('https://api.lusha.com/v3/contacts/signal-score', 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/signal-score")
.header("api_key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"contacts\": [\n {\n \"clientReferenceId\": \"ref-1\",\n \"id\": \"v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345\"\n },\n {\n \"clientReferenceId\": \"ref-2\",\n \"linkedinUrl\": \"https://linkedin.com/in/johndoe\"\n },\n {\n \"clientReferenceId\": \"ref-3\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"companyDomain\": \"acme.com\"\n }\n ]\n}")
.asString();package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.lusha.com/v3/contacts/signal-score"
payload := strings.NewReader("{\n \"contacts\": [\n {\n \"clientReferenceId\": \"ref-1\",\n \"id\": \"v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345\"\n },\n {\n \"clientReferenceId\": \"ref-2\",\n \"linkedinUrl\": \"https://linkedin.com/in/johndoe\"\n },\n {\n \"clientReferenceId\": \"ref-3\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"companyDomain\": \"acme.com\"\n }\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": "5d6f13d2-f6b0-4e55-85d5-04e17f932c1a",
"results": [
{
"clientReferenceId": "ref-1",
"id": "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345",
"fullName": "Jane Doe",
"company": {
"id": "v1.6789ZyXwVuTsRqPoNmLkJiHgFeDcBa01",
"name": "Acme Corp",
"domain": "acme.com"
},
"signalScore": 0.3,
"signalTypes": [
"promotion"
],
"noActiveSignals": false
},
{
"clientReferenceId": "ref-2",
"error": {
"code": "NOT_FOUND",
"message": "Contact not found"
}
}
],
"billing": {
"creditsCharged": 1,
"resultsReturned": 1
}
}