# Webhook Subscriptions: Clean Employee API

## Overview

The topic introduces the main information for Clean Employee API webhook subscriptions.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Webhook subscriptions</strong></td><td>Try to simulate a subscription and explore subscription management options</td><td><a href="../../../api-introduction/webhooks">webhooks</a></td></tr><tr><td><strong>Employee webhooks</strong></td><td>General information on how Employee Webhooks work</td><td><a href="../../../api-introduction/webhooks/employee-webhooks">employee-webhooks</a></td></tr><tr><td><strong>Experience webhooks</strong></td><td>General information on how Experience Webhooks work</td><td><a href="../../../api-introduction/webhooks/experience-webhooks">experience-webhooks</a></td></tr></tbody></table>

There are two types of webhook subscriptions available:

| Feature          | Employee profile changes                   | Experience changes               |
| ---------------- | ------------------------------------------ | -------------------------------- |
| Update frequency | Weekly                                     | Weekly                           |
| Webhook triggers | 100+ data fields (Skills, Education, etc.) | Job starts, promotions or ends   |
| Best for         | Monitoring general profile updates         | Tracking employee career changes |

***

### Subscription method

You can subscribe to updates using three different methods. Use the `Subscription method` column to find the correct endpoint for your needs.

| Subscription method  | Employee profile changes subscription endpoint | Experience changes subscription endpoint                     |
| -------------------- | ---------------------------------------------- | ------------------------------------------------------------ |
| By ID List           | `/v2/subscriptions/employee_clean/ids`         | `/v2/subscriptions/experience_changes/employee_clean/ids`    |
| By Elasticsearch DSL | `/v2/subscriptions/employee_clean/es_dsl`      | `/v2/subscriptions/experience_changes/employee_clean/es_dsl` |
| By all updates       | –                                              | `/v2/subscriptions/experience_changes/employee_clean/all`    |

## Webhook payload

See what information is included in webhook notifications.

<details>

<summary>Employee webhooks</summary>

Each webhook notification includes the following fields:

* `member_id` – The ID of the employee profile that was updated.
* `status` – The type of change detected (see status values below).
* `changed_fields` – An array listing the specific fields that were modified on the profile.

{% code title="Example payload" %}

```json
[
  {
    "member_id": 123,
    "status": "started_matching_query",
    "changed_fields": null
  },
  {
    "member_id": 124,
    "status": "stopped_matching_query",
    "changed_fields": null
  },
  {
    "member_id": 125,
    "status": "changed",
    "changed_fields": ["skills", "headline", "certifications"]
  }
]
```

{% endcode %}

The `changed_fields` array tells you exactly which parts of the profile were modified. You can use this to decide whether to retrieve the full updated profile or skip the notification based on your use case.

</details>

<details>

<summary>Experience webhooks</summary>

Each webhook notification includes the following fields:

* `member_id` – The ID of the employee profile that was updated.
* `status` – Notifies a changed state.

{% code title="Example payload" %}

```json
[
  {
    "member_id": 125,
    "status": "changed"
  }
]
```

{% endcode %}

</details>

## Webhook triggers

Identify the Clean Employee fields that trigger Employee profile changes notifications.

<details>

<summary>Fields that trigger webhooks</summary>

| Field                                                         | Change type                 |
| ------------------------------------------------------------- | --------------------------- |
| `activity`                                                    | `new`, `deleted`            |
| `activity.action`                                             | `new`, `updated`, `deleted` |
| `activity.activity_url`                                       | `new`, `updated`, `deleted` |
| `activity.id`                                                 | `new`, `updated`, `deleted` |
| `activity.title`                                              | `new`, `updated`, `deleted` |
| `awards`                                                      | `new`, `deleted`            |
| `awards.date`                                                 | `new`, `updated`, `deleted` |
| `awards.description`                                          | `new`, `updated`, `deleted` |
| `awards.id`                                                   | `new`, `updated`, `deleted` |
| `awards.issuer`                                               | `new`, `updated`, `deleted` |
| `awards.title`                                                | `new`, `updated`, `deleted` |
| `certifications`                                              | `new`, `deleted`            |
| `certifications.certificate_logo_url`                         | `new`, `updated`, `deleted` |
| `certifications.certificate_url`                              | `new`, `updated`, `deleted` |
| `certifications.date_from`                                    | `new`, `updated`, `deleted` |
| `certifications.date_to`                                      | `new`, `updated`, `deleted` |
| `certifications.id`                                           | `new`, `updated`, `deleted` |
| `certifications.issuer`                                       | `new`, `updated`, `deleted` |
| `certifications.issuer_url`                                   | `new`, `updated`, `deleted` |
| `certifications.title`                                        | `new`, `updated`, `deleted` |
| `company_id`                                                  | `new`, `updated`, `deleted` |
| `connections_count`                                           | `updated`                   |
| `courses`                                                     | `new`, `deleted`            |
| `courses.id`                                                  | `new`, `updated`, `deleted` |
| `courses.organizer`                                           | `new`, `updated`, `deleted` |
| `courses.title`                                               | `new`, `updated`, `deleted` |
| `department`                                                  | `new`, `updated`, `deleted` |
| `description`                                                 | `new`, `updated`, `deleted` |
| `education`                                                   | `new`, `deleted`            |
| `education.activities_and_societies`                          | `new`, `updated`, `deleted` |
| `education.date_from`                                         | `new`, `updated`, `deleted` |
| `education.date_to`                                           | `new`, `updated`, `deleted` |
| `education.description`                                       | `new`, `updated`, `deleted` |
| `education.id`                                                | `new`, `updated`, `deleted` |
| `education.institution_logo_url`                              | `new`, `updated`, `deleted` |
| `education.institution_url`                                   | `new`, `updated`, `deleted` |
| `education.major`                                             | `new`, `updated`, `deleted` |
| `education.title`                                             | `new`, `updated`, `deleted` |
| `experience`                                                  | `new`, `deleted`            |
| `experience.company_annual_revenue`                           | `new`, `updated`, `deleted` |
| `experience.company_annual_revenue_currency`                  | `new`, `deleted`            |
| `experience.company_categories_and_keywords`                  | `new`, `updated`, `deleted` |
| `experience.company_employees_count_change_yearly_percentage` | `new`, `updated`, `deleted` |
| `experience.company_facebook_url`                             | `new`, `updated`, `deleted` |
| `experience.company_followers_count`                          | `new`, `updated`, `deleted` |
| `experience.company_founded`                                  | `new`, `updated`, `deleted` |
| `experience.company_id`                                       | `new`, `updated`, `deleted` |
| `experience.company_industry`                                 | `new`, `updated`, `deleted` |
| `experience.company_is_b2b`                                   | `new`, `updated`, `deleted` |
| `experience.company_last_funding_round_amount_raised`         | `new`, `updated`, `deleted` |
| `experience.company_last_funding_round_announced_date`        | `new`, `updated`, `deleted` |
| `experience.company_last_updated`                             | `new`, `updated`, `deleted` |
| `experience.company_professionnal_network_url`                | `new`, `updated`, `deleted` |
| `experience.company_location_hq_city`                         | `new`, `updated`, `deleted` |
| `experience.company_location_hq_country`                      | `new`, `updated`, `deleted` |
| `experience.company_location_hq_country_iso2`                 | `new`, `updated`, `deleted` |
| `experience.company_location_hq_country_iso3`                 | `new`, `updated`, `deleted` |
| `experience.company_location_hq_full_address`                 | `new`, `updated`, `deleted` |
| `experience.company_location_hq_regions`                      | `new`, `updated`, `deleted` |
| `experience.company_location_hq_state`                        | `new`, `updated`, `deleted` |
| `experience.company_location_hq_street`                       | `new`, `updated`, `deleted` |
| `experience.company_location_hq_zipcode`                      | `new`, `updated`, `deleted` |
| `experience.company_logo_url`                                 | `new`, `updated`, `deleted` |
| `experience.company_name`                                     | `new`, `updated`, `deleted` |
| `experience.company_size_employees_count`                     | `new`, `updated`, `deleted` |
| `experience.company_size_range`                               | `new`, `updated`, `deleted` |
| `experience.company_stock_ticker`                             | `new`, `updated`, `deleted` |
| `experience.company_twitter_url`                              | `new`, `updated`, `deleted` |
| `experience.company_type`                                     | `new`, `updated`, `deleted` |
| `experience.company_website`                                  | `new`, `updated`, `deleted` |
| `experience.date_from`                                        | `new`, `updated`, `deleted` |
| `experience.date_to`                                          | `new`, `updated`, `deleted` |
| `experience.department`                                       | `new`, `updated`, `deleted` |
| `experience.duration`                                         | `new`, `updated`, `deleted` |
| `experience.duration_months`                                  | `new`, `updated`, `deleted` |
| `experience.experience_description`                           | `new`, `updated`, `deleted` |
| `experience.id`                                               | `new`, `updated`, `deleted` |
| `experience.location`                                         | `new`, `updated`, `deleted` |
| `experience.management_level`                                 | `new`, `updated`, `deleted` |
| `experience.title`                                            | `new`, `updated`, `deleted` |
| `follower_count`                                              | `new`, `updated`, `deleted` |
| `full_name`                                                   | `new`, `updated`, `deleted` |
| `generated_headline`                                          | `new`, `updated`, `deleted` |
| `headline`                                                    | `new`, `updated`, `deleted` |
| `is_decision_maker`                                           | `new`, `updated`, `deleted` |
| `is_deleted`                                                  | `updated`                   |
| `is_hidden`                                                   | `new`, `updated`, `deleted` |
| `is_working`                                                  | `new`, `updated`            |
| `job_description`                                             | `new`, `updated`, `deleted` |
| `job_title`                                                   | `new`, `updated`, `deleted` |
| `languages`                                                   | `new`, `deleted`            |
| `languages.id`                                                | `new`, `updated`, `deleted` |
| `languages.language`                                          | `new`, `updated`, `deleted` |
| `languages.proficiency`                                       | `new`, `updated`, `deleted` |
| `location_city`                                               | `new`, `updated`, `deleted` |
| `location_country`                                            | `new`, `updated`, `deleted` |
| `location_country_iso_2`                                      | `new`, `updated`, `deleted` |
| `location_country_iso_3`                                      | `new`, `updated`, `deleted` |
| `location_raw_address`                                        | `new`, `updated`, `deleted` |
| `location_regions`                                            | `updated`                   |
| `location_state`                                              | `new`, `updated`, `deleted` |
| `management_level`                                            | `new`, `updated`, `deleted` |
| `member_quality`                                              | `updated`                   |
| `name_first`                                                  | `new`, `updated`, `deleted` |
| `name_last`                                                   | `new`, `updated`, `deleted` |
| `name_middle`                                                 | `new`, `updated`, `deleted` |
| `organizations`                                               | `new`, `deleted`            |
| `organizations.date_from`                                     | `new`, `updated`, `deleted` |
| `organizations.date_to`                                       | `new`, `updated`, `deleted` |
| `organizations.description`                                   | `new`, `updated`, `deleted` |
| `organizations.id`                                            | `new`, `updated`, `deleted` |
| `organizations.organization`                                  | `new`, `updated`, `deleted` |
| `organizations.position`                                      | `new`, `updated`, `deleted` |
| `patents`                                                     | `new`, `deleted`            |
| `patents.date`                                                | `new`, `updated`, `deleted` |
| `patents.description`                                         | `new`, `updated`, `deleted` |
| `patents.id`                                                  | `new`, `updated`, `deleted` |
| `patents.inventors`                                           | `new`, `updated`, `deleted` |
| `patents.patent_or_application_number`                        | `new`, `updated`, `deleted` |
| `patents.patent_url`                                          | `new`, `updated`, `deleted` |
| `patents.status`                                              | `new`, `updated`, `deleted` |
| `patents.title`                                               | `new`, `updated`, `deleted` |
| `picture_url`                                                 | `new`, `updated`, `deleted` |
| `public_profile_id`                                           | `new`, `updated`, `deleted` |
| `publications`                                                | `new`, `deleted`            |
| `publications.authors`                                        | `new`, `updated`, `deleted` |
| `publications.date`                                           | `new`, `updated`, `deleted` |
| `publications.description`                                    | `new`, `updated`, `deleted` |
| `publications.id`                                             | `new`, `updated`, `deleted` |
| `publications.publication_url`                                | `new`, `updated`, `deleted` |
| `publications.publisher`                                      | `new`, `updated`, `deleted` |
| `publications.title`                                          | `new`, `updated`, `deleted` |
| `recommendations`                                             | `new`, `deleted`            |
| `recommendations.id`                                          | `new`, `deleted`            |
| `recommendations.recommendation`                              | `new`, `deleted`            |
| `recommendations.referee_name`                                | `new`, `deleted`            |
| `recommendations.referee_url`                                 | `new`, `deleted`            |
| `recommendations_count`                                       | `updated`                   |
| `shorthand_names`                                             | `updated`                   |
| `skills`                                                      | `new`, `updated`            |
| `total_experience_duration`                                   | `new`, `updated`            |
| `total_experience_duration_months`                            | `new`, `updated`            |
| `websites_professionnal_network`                              | `updated`                   |

</details>

## Trackable fields

The following fields can be used with the `tracked_fields` parameter (subscribe by field) and will appear in the `changed_fields` array in webhook payloads. This list is used to track changes via Employee Webhook subscriptions.

<details>

<summary>Tracked fields list</summary>

| Field                              | Field                    | Field                       |
| ---------------------------------- | ------------------------ | --------------------------- |
| `id`                               | `company_id`             | `full_name`                 |
| `name_first`                       | `name_middle`            | `name_last`                 |
| `websites_professionnal_network`   | `description`            | `job_title`                 |
| `management_level`                 | `department`             | `is_decision_maker`         |
| `is_working`                       | `job_description`        | `recommendations_count`     |
| `connections_count`                | `location_raw_address`   | `location_country`          |
| `location_country_iso_2`           | `location_country_iso_3` | `location_state`            |
| `location_city`                    | `is_deleted`             | `is_hidden`                 |
| `follower_count`                   | `headline`               | `generated_headline`        |
| `picture_url`                      | `public_profile_id`      | `total_experience_duration` |
| `total_experience_duration_months` | `member_quality`         | `skills`                    |
| `shorthand_names`                  | `location_regions`       | `experience`                |
| `education`                        | `languages`              | `certifications`            |
| `courses`                          | `awards`                 | `activity`                  |
| `organizations`                    | `patents`                | `publications`              |
| `recommendations`                  |                          |                             |

</details>

## Employee webhooks

### Subscribe by IDs

Get notifications if one of webhook triggers has been updated:

```json
curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/employee_clean/ids' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: multipart/form-data' \
  -d '{
  "webhook_url": "{your_webhook_url}",
  "ids": [1, 222, 3456]
}'
```

Subscribe by field and track `skills` changes:

```json
curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/employee_clean/ids' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: multipart/form-data' \
  -d '{
  "webhook_url": "{your_webhook_url}",
  "ids": [1, 222, 3456],
  "tracked_fields": ["skills"]
}'
```

### Subscribe by Elasticsearch DSL

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Clean Employee API Elasticsearch DSL</td><td><a href="elasticsearch-dsl">elasticsearch-dsl</a></td></tr></tbody></table>

{% hint style="warning" %}

#### **Unavailable filters**

`last_updated` cannot be used in subscription Elasticsearch DSL queries.
{% endhint %}

Get notifications if one of webhook triggers has been updated:

```json
curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/employee_clean/es_dsl' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "webhook_url": "{your_webhook_url}",
  "es_dsl_query": {
    "query": {
      "match": {
        "full_name": {
          "query": "John Smith",
          "operator": "and"
        }
      }
    }
  }
}'
```

Subscribe by fields and track `experience` and `headline` changes:

```json
curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/employee_clean/es_dsl' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "webhook_url": "{your_webhook_url}",
  "es_dsl_query": {
    "query": {
      "match": {
        "full_name": {
          "query": "John Smith",
          "operator": "and"
        }
      }
    }
  },
  "tracked_fields": ["experience", "headline"]
}'
```

***

## Experience webhooks

### Subscribe by IDs

```json
curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/experience_changes/employee_clean/ids' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: multipart/form-data' \
  -d '{
  "webhook_url": "{your_webhook_url}",
  "ids": [1, 222, 3456]
}'
```

### Subscribe by Elasticsearch DSL

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Clean Employee API Elasticsearch DSL</td><td><a href="elasticsearch-dsl">elasticsearch-dsl</a></td></tr></tbody></table>

{% hint style="warning" %}

#### **Unavailable filters**

`last_updated` cannot be used in subscription Elasticsearch DSL queries.
{% endhint %}

```json
curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/experience_changes/employee_clean/es_dsl' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "webhook_url": "{your_webhook_url}",
  "es_dsl_query": {
    "query": {
      "match": {
        "full_name": {
          "query": "John Smith",
          "operator": "and"
        }
      }
    }
  }
}'
```

### Subscribe to all profiles

```json
curl -X 'POST' \
  'https://api.coresignal.com/cdapi/v2/subscriptions/experience_changes/employee_clean/all' \
  -H 'accept: application/json' \
  -H 'apikey: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "webhook_url": "{your_webhook_url}"
}'
```

## Retrieving updated profile data

After receiving a webhook notification, use the `changed_fields` array to determine if you need to fetch the updated profile data.

### Single profile update

To see the exact changes in one profile, you will have to use the employee ID (`member_id`) in the following endpoint:

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Clean Employee API collection endpoint</td><td><a href="collect">collect</a></td></tr></tbody></table>

### Multiple profile updates

To identify the changes in multiple profiles, you need to export the employee IDs and use them with the following Bulk Collect endpoints:

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Clean Employee API Bulk Collect endpoints</td><td><a href="bulk-collect">bulk-collect</a></td></tr></tbody></table>

Follow the instructions here to successfully collect the employee data:

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>IDs request</td><td><a href="../../../../api-introduction/requests/bulk-collect/post-requests#id-file-requests">#id-file-requests</a></td></tr><tr><td>GET the file name</td><td><a href="../../../../api-introduction/requests/bulk-collect/get-requests#get-the-file-name">#get-the-file-name</a></td></tr><tr><td>GET the file</td><td><a href="../../../../api-introduction/requests/bulk-collect/get-requests#get-the-file">#get-the-file</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coresignal.com/employee-api/clean-employee-api/endpoints/webhook-subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.