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)
linkedinUrl
email
firstName + lastName + (companyName or companyDomain)

Each result is one of:

A scored entry - signalScore, signalTypes, and noActiveSignals.
A NOT_FOUND entry - identity resolution failed for the supplied identifier.
A NO_SCORE entry - 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 retryable 502 instead, 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.creditsCharged is 0). Error rows (NOT_FOUND / NO_SCORE) are never charged.

POST

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

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

contacts

object[]

required

Required array length: 1 - 100 elements

Show child attributes

Response

Successful response

requestId

string<uuid>

Example:

"5d6f13d2-f6b0-4e55-85d5-04e17f932c1a"

results

object[]

Show child attributes

billing

object

Credit usage summary for a V3 API request

Show child attributes

⌘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
  }
}

Overview

Resources

Endpoints

Score Contacts by Signal Activity

Authorizations

Body

Response