Contact Signals

POST

contacts

signals

Contact Signals

curl --request POST \
  --url https://api.lusha.com/v3/contacts/signals \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "ids": [
    "4389064624",
    "4389064654"
  ],
  "signalTypes": [
    "allSignals"
  ],
  "startDate": "2025-01-01"
}
'

import requests

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

payload = {
    "ids": ["4389064624", "4389064654"],
    "signalTypes": ["allSignals"],
    "startDate": "2025-01-01"
}
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({
    ids: ['4389064624', '4389064654'],
    signalTypes: ['allSignals'],
    startDate: '2025-01-01'
  })
};

fetch('https://api.lusha.com/v3/contacts/signals', 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/signals")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ids\": [\n    \"4389064624\",\n    \"4389064654\"\n  ],\n  \"signalTypes\": [\n    \"allSignals\"\n  ],\n  \"startDate\": \"2025-01-01\"\n}")
  .asString();

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"ids\": [\n    \"4389064624\",\n    \"4389064654\"\n  ],\n  \"signalTypes\": [\n    \"allSignals\"\n  ],\n  \"startDate\": \"2025-01-01\"\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))

}

{
  "results": [
    {
      "id": "4389064624",
      "companyChange": [],
      "promotion": []
    }
  ],
  "startDate": "2025-01-01",
  "endDate": "2025-07-31",
  "billing": {
    "creditsCharged": 2,
    "resultsReturned": 1
  }
}

Use this endpoint when you already have Lusha contact IDs and want their signal activity - promotions and company changes - in one call. Pass up to 100 ids and the signalTypes you want back; there is no separate “search” step in V3 - one call returns all matched signal data for the IDs you send.

Don’t have Lusha contact IDs yet? Resolve contacts first with Enrich Contacts or Search & Enrich Contacts, then pass the returned id values here.

Endpoint

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

Authentication: API key (ApiKeyAuth)

Request body

string[]

required

Lusha contact IDs to retrieve signals for. 1–100 items per request.Example: ["4389064624", "4389064654"]

string[]

required

Signal types to retrieve.Allowed values: allSignals, promotion, companyChangeUse allSignals to retrieve every available contact signal type in one call.

string

Limit results to signals detected on or after this date, in YYYY-MM-DD format.Example: "2025-01-01"

integer

Maximum number of signal instances to return per signal type per contact. Range: 1–100.Example: 10

Example request

curl --request POST \
  --url https://api.lusha.com/v3/contacts/signals \
  --header 'api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ids": ["4389064624", "4389064654"],
    "signalTypes": ["allSignals"],
    "startDate": "2025-01-01"
  }'

{
  "ids": ["4389064624", "4389064654"],
  "signalTypes": ["allSignals"],
  "startDate": "2025-01-01"
}

Response

200 - Success

object[]

One entry per requested contact ID.

Show properties

string

The Lusha contact ID this entry corresponds to. Example: "4389064624"

object[]

Matched companyChange signal events for this contact, newest first. Only present when companyChange (or allSignals) was requested and at least one event matched.

object[]

Matched promotion signal events for this contact, newest first. Only present when promotion (or allSignals) was requested and at least one event matched.

string

The start date used for this request.

string

The end date used for this request (the request date, unless you’re querying historical data).

object

Credit usage summary for this request.

Show properties

integer

Credits charged for this request. Example: 2

integer

Number of results returned. Example: 1

object

Present only when you pass tableId on the request. Summarizes what was written to the table. The rest of the response is unaffected even if the table write fails.

Show properties

string

The table that was written to. Example: 482910

integer

New entities added to the table by this call.

integer

Entities from this call that were already in the table.

integer

Columns auto-created by this call, for example a Signals column created on first use.

integer

Rows the column run touched as part of this call.

integer

Rows that incurred a credit charge.

integer

Rows already paid for in this table, which were not charged again.

integer

Credits charged for this table write.

Billing: Charged per matched signal per result via the showSignalsContact action.

{
  "results": [
    {
      "id": "4389064624",
      "companyChange": [],
      "promotion": []
    }
  ],
  "startDate": "2025-01-01",
  "endDate": "2025-07-31",
  "billing": {
    "creditsCharged": 2,
    "resultsReturned": 1
  }
}

Error codes

Status	Meaning
`400`	Bad request - invalid input data.
`401`	Unauthorized - your API key is missing or invalid.
`402`	Payment required - insufficient credits.
`403`	Forbidden - account inactive or V3 access not enabled.
`429`	Too many requests - you have exceeded the rate limit.

Signals overview - the consolidated signals model, credits, and delivery options
Get Contact Signal Types - the current list of valid signalTypes values
Company Signals - the equivalent endpoint for companies

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

ids

string[]

required

Required array length: 1 - 100 elements

Example:

["4389064624", "4389064654"]

signalTypes

enum<string>[]

required

Available options:

allSignals,

promotion,

companyChange

Example:

["allSignals"]

startDate

string<date>

Example:

"2025-01-01"

maxResultsPerSignal

integer

Required range: 1 <= x <= 100

Example:

10

tableId

string

Optional. If provided, these contacts are also added to this table (if not already present) and the Signals column is populated. See the Tables API.

Example:

"482910"

Response

Successful response

results

object[]

Show child attributes

startDate

string

endDate

string

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

Contact Signals

curl --request POST \
  --url https://api.lusha.com/v3/contacts/signals \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "ids": [
    "4389064624",
    "4389064654"
  ],
  "signalTypes": [
    "allSignals"
  ],
  "startDate": "2025-01-01"
}
'

import requests

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

payload = {
    "ids": ["4389064624", "4389064654"],
    "signalTypes": ["allSignals"],
    "startDate": "2025-01-01"
}
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({
    ids: ['4389064624', '4389064654'],
    signalTypes: ['allSignals'],
    startDate: '2025-01-01'
  })
};

fetch('https://api.lusha.com/v3/contacts/signals', 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/signals")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ids\": [\n    \"4389064624\",\n    \"4389064654\"\n  ],\n  \"signalTypes\": [\n    \"allSignals\"\n  ],\n  \"startDate\": \"2025-01-01\"\n}")
  .asString();

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"ids\": [\n    \"4389064624\",\n    \"4389064654\"\n  ],\n  \"signalTypes\": [\n    \"allSignals\"\n  ],\n  \"startDate\": \"2025-01-01\"\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))

}

{
  "results": [
    {
      "id": "4389064624",
      "companyChange": [],
      "promotion": []
    }
  ],
  "startDate": "2025-01-01",
  "endDate": "2025-07-31",
  "billing": {
    "creditsCharged": 2,
    "resultsReturned": 1
  }
}

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

​Related pages

Authorizations

Body

Response

Endpoint

Request body

Example request

Response

200 - Success

Error codes

Related pages