# April 2025

## Multi-source Employee data

### 🆕 New fields

**Effective from:** April 9, 2025

| Field Name          | Type             | Description                                    |
| ------------------- | ---------------- | ---------------------------------------------- |
| `public_profile_id` | Number (long)    | Public profile ID                              |
| `historical_skills` | Array of strings | Previously reported skills                     |
| `description`       | String           | Experience description (in Experience section) |

**Reference:**\
See updated field definitions in the [Multi-source Employee Data dictionary](https://app.gitbook.com/s/cyJAXlZjTKSLvAQjb9rM/employee-data/multi-source-employee-data/dictionary-multi-source-employee-data).

## Multi-source Company data

### 🔁 Field renaming: `member_id` → `parent_id`

**Effective from:** April 2025 Delivery

| Field Name (Before)                  | Field Name (After)                   | Type             |
| ------------------------------------ | ------------------------------------ | ---------------- |
| `key_executives.member_id`           | `key_executives.parent_id`           | Number (integer) |
| `key_executive_arrivals.member_id`   | `key_executive_arrivals.parent_id`   | Number (integer) |
| `key_executive_departures.member_id` | `key_executive_departures.parent_id` | Number (integer) |

**Note:** This is a structural change. Clients parsing key executive data should update their ingestion logic accordingly.

## Employee data

### 🆕 New fields

**Effective from:** April 2025 Delivery

| Field Name                        | Type           | Description                                                               |
| --------------------------------- | -------------- | ------------------------------------------------------------------------- |
| `experience.company_source_id`    | Number (int64) | Record ID assigned by a professional network for companies in experience  |
| `education.institution_id`        | Number (int64) | Company ID (institution) relating to the company table                    |
| `education.institution_source_id` | Number (int64) | Record ID assigned by a professional network for educational institutions |

## Base Employee API

### Migration timeline

| Date           | Change                                                    |
| -------------- | --------------------------------------------------------- |
| April 9, 2025  | Base Employee API released; migration period begins       |
| May 9, 2025    | Subscriptions to Employee API disabled                    |
| August 6, 2025 | Employee API fully deprecated; Base Employee API required |

***

### Key enhancements

* New fields: `follower_count`, `checked_at`, `services`
* New collections: `historical_ids`, `shorthand_names`, `activity`
* Duplicate handling: via `is_parent` 
* Streamlined data model and cleaner output
* Webhooks sent daily
* Enhanced Elasticsearch schema and filters

***

### Endpoint comparison

#### 🔍 **Search endpoints**

| Query type        | Employee API Endpoint                           | Base Employee API Endpoint                             |
| ----------------- | ----------------------------------------------- | ------------------------------------------------------ |
| Search Filter     | `/v1/professional_network/member/search/filter` | `/v1/professional_network/employee_base/search/filter` |
| Elasticsearch DSL | `/v1/professional_network/member/search/es_dsl` | `/v1/professional_network/employee_base/search/es_dsl` |

***

#### 📦 **Collect endpoints**

| Type                 | Employee API Endpoint                                      | Base Employee API Endpoint                                        |
| -------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------- |
| Collect by Member ID | `/v1/professional_network/member/collect/{member_id}`      | `/v1/professional_network/employee_base/collect/{employee_id}`    |
| Collect by Shorthand | `/v1/professional_network/member/collect/{shorthand_name}` | `/v1/professional_network/employee_base/collect/{shorthand_name}` |

***

#### 🔁 **ID mapping endpoint**

Since the IDs of Employee API will not be the same as Base Employee API, we've prepared a mapping endpoint for mapping purposes. This means that the valid, non-duplicate data you already have can be used in the Base Employee API. The mapping endpoint is listed below:

| Action         | Endpoint                                         |
| -------------- | ------------------------------------------------ |
| Map Old to New | `/v1/professional_network/employee_base/map/ids` |

***

#### 📩 **Bulk Collect endpoints**

**Note:** `id_file` is no longer supported — use `ids` array instead.\
**Recommendation:** Add this clause to target non-duplicate records:

```json
 "term": {
            "is_parent": 1
 }
```

| Action                 | Employee API Endpoint                                  | Base Employee API Endpoint                                   |
| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| Bulk Collect by IDs    | `/v1/professional_network/member/bulk_collect/id_file` | `/v1/professional_network/employee_base/bulk_collect/ids` ❗  |
| Bulk Collect by Filter | `/v1/professional_network/member/bulk_collect/filter`  | `/v1/professional_network/employee_base/bulk_collect/filter` |
| Bulk Collect by ES DSL | `/v1/professional_network/member/bulk_collect/es_dsl`  | `/v1/professional_network/employee_base/bulk_collect/es_dsl` |

#### 📤 Data not included in Bulk Collect (temporary)

| Category     | Data field     |
| ------------ | -------------- |
| Publications | `authors`      |
| Patents      | `inventors`    |
| Projects     | `team_members` |

***

#### 🔔 **Webhook Subscription endpoints**

| Action              | Employee API Endpoint                                   | Base Employee API Endpoint                                    |
| ------------------- | ------------------------------------------------------- | ------------------------------------------------------------- |
| Subscribe by IDs    | `/v1/subscriptions/professional_network/member/id_file` | `/v1/subscriptions/professional_network/employee_base/ids` ❗  |
| Subscribe by Filter | `/v1/subscriptions/professional_network/member/filter`  | `/v1/subscriptions/professional_network/employee_base/filter` |
| Subscribe by ES DSL | `/v1/subscriptions/professional_network/member/es_dsl`  | `/v1/subscriptions/professional_network/employee_base/es_dsl` |

***

## Multi-source Employee API

### 🆕 New fields

**Effective from:** April 9, 2025

| Action | Field Name          | Type             | Description                                        |
| ------ | ------------------- | ---------------- | -------------------------------------------------- |
| Added  | `public_profile_id` | Number (long)    | Public profile ID                                  |
| Added  | `historical_skills` | Array of strings | Previously observed skills                         |
| Added  | `description`       | String           | Job description (added in the `experience` object) |

## Bulk Collect

### ⚠️ Bulk Collect limit

**Release date:** April 2, 2025

**New rule:**\
A single Bulk Collect request cannot retrieve more than **10,000 profiles**. This applies to:

* ID list uploads
* Filter-based requests
* Elasticsearch DSL-based requests

**Error handling:**

| Code | Scenario                              | Message                                               |
| ---- | ------------------------------------- | ----------------------------------------------------- |
| 400  | ID list exceeds 10,000 profiles       | `File contains too many IDs. Maximum is 10,000 IDs`   |
| 422  | Filter results exceed 10,000 profiles | `Request matched too many IDs. Maximum is 10,000 IDs` |
| 422  | ES DSL results exceed 10,000 profiles | `Request matched too many IDs. Maximum is 10,000 IDs` |

**Behavioral notes:**

* ID list violations block request creation immediately.
* Filter/Elasticsearch DSL overages are rejected **after** request creation, during processing.
  * Clients are notified via webhook (if `webhook_url` was provided).

***

### 🔁 Bulk Collect response code update

**Release date:** April 30, 2025\
All successful Bulk Collect requests will now return **HTTP 201 (Created)** instead of **HTTP 200**.

**Impacted endpoints:**

```
/v2/data_requests/employee_clean/id_file
/v2/data_requests/employee_clean/es_dsl
/v2/data_requests/company_base/id_file
/v2/data_requests/company_base/filter
/v2/data_requests/company_base/filter/flat_csv
/v2/data_requests/company_base/es_dsl
/v2/data_requests/job_base/id_file
/v2/data_requests/job_base/filter
/v2/data_requests/job_base/filter/flat_csv
/v2/data_requests/member/id_file
/v2/data_requests/member/filter
/v2/data_requests/member/filter/flat_csv
/v2/data_requests/member/es_dsl
```

## Webhook subscriptions

### Breaking changes: c**hanges value renaming for webhooks**:

#### The `change type` values sent via webhook have been updated:

* `added` → `started_matching_query`
* `removed` → `stopped_matching_query`
* `changed_experience` → `changed`

These updates affect all webhook endpoints and went live on April 30th, 2025.