> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusha.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve contact signals for company changes and promotions

> Fetch company change and promotion signals for up to 100 contacts per request using their Lusha contact IDs.

Contact signals tell you when someone in your pipeline or CRM has changed jobs or received a promotion. One endpoint takes up to 100 Lusha contact IDs and the signal types you want, and returns everything that matched - no separate lookup or search step.

> [!NOTE]
>
> Signals are charged per matched signal per result. Request only the signal types you need.

## Signal types for contacts

| Signal type | Description |
| - | - |
| `allSignals` | All available contact signal types |
| `promotion` | Job title promotions within the same company |
| `companyChange` | Moves to a new employer |

> [!TIP]
>
> Call [Get Contact Signal Types](https://docs.lusha.com/api-reference/signals/contact-signal-types) to fetch this list programmatically instead of hardcoding it.

## Get contact signals

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

Send 1–100 Lusha contact IDs per request along with the `signalTypes` you want. Use `startDate` to limit results to signals detected on or after a given date, and `maxResultsPerSignal` to cap how many instances of each signal type come back per contact.

**Request body**

| Field | Type | Required | Description |
| - | - | - | - |
| `ids` | array of strings | Yes | Lusha contact IDs, 1–100 per request |
| `signalTypes` | array of strings | Yes | Signal types to retrieve: `allSignals`, `promotion`, `companyChange` |
| `startDate` | string | No | Earliest date for signals, in `YYYY-MM-DD` format |
| `maxResultsPerSignal` | integer | No | Maximum signal instances returned per type per contact (1–100) |

**Example request**

```json theme={null}
{
  "ids": ["4389064624", "4389064654"],
  "signalTypes": ["allSignals"],
  "startDate": "2025-01-01"
}
```

**Example response**

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

Matched events for each requested signal type appear directly on the result under that type's key (`promotion`, `companyChange`) - there's no wrapper object to unpack.

## If you don't have contact IDs yet

Contact Signals only accepts Lusha contact IDs. If you're starting from a LinkedIn URL, email, or name, resolve the contact first, then retrieve signals for the returned ID:

**1. Resolve the contact**

Call [Enrich Contacts](https://docs.lusha.com/enrichment/enrich-contacts.md) or [Search & Enrich Contacts](https://docs.lusha.com/enrichment/search-and-enrich-contacts.md) to get a Lusha contact `id`.

**2. Retrieve signals for that ID**

Pass the `id` into `POST /v3/contacts/signals`.

## Related pages

* [Signals overview](https://docs.lusha.com/signals/overview.md) - the consolidated signals model, credits, and delivery options
* [Company signals](https://docs.lusha.com/signals/company-signals.md) - retrieve signals for companies
* [API reference: Contact Signals](https://docs.lusha.com/api-reference/signals/contact-signals.md) - full request/response schema


## Related topics

- [Detect contact and company signals with Lusha](https://docs.lusha.com/signals/overview.md)
- [Contact Signals](https://docs.lusha.com/api-reference/signals/contact-signals.md)
- [Retrieve company signals for business events and growth](https://docs.lusha.com/signals/company-signals.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.