# View worker changes

> Query, filter, and track HR profile change events using the Worker Changes API.

Query, filter, and track HR profile change events using the Worker Changes API.

## Overview

Use the Worker Changes API to query a feed of HR profile events, including new hires, employee profile field updates, scheduled worker changes, offboardings, and employee date changes.

Every worker change event is tracked using two timestamps:

-   `applied_on` - When Rippling saved or approved the record. This timestamp increases as changes are written.
-   `effective_on` - When the change takes effect (past, present, or future). Indicates when a salary change, title change, or hire officially applies.

It's recommended to poll change events using `applied_on`. Filtering by `effective_on` will not include changes scheduled at a future date (e.g., a promotion that takes effect a month from today).

Common use cases include:

-   **Sync compensation updates**: Call [GET List worker changes](https://developer.rippling.com/documentation/rest-api/reference/list-worker-changes) by the compensation `field_key` values to keep rewards systems updated with recent and future-dated salary changes.
-   **Audit worker history**: Filter events by `worker_id` to build a complete timeline of an employee's lifecycle from hire to current role.
-   **View access provisioning records**: Inspect a worker's hire, department change, and offboarding events to see when user accounts were created, updated, or revoked.

### Available endpoints

| Endpoint | Description |
| --- | --- |
| [GET List worker change fields](https://developer.rippling.com/documentation/rest-api/reference/list-worker-change-fields) | Retrieve the full catalog of trackable fields, data types, and categories. |
| [GET List worker changes](https://developer.rippling.com/documentation/rest-api/reference/list-worker-changes) | Fetch a paginated, filterable feed of worker profile change events. |
| [GET Retrieve a specific worker change](https://developer.rippling.com/documentation/rest-api/reference/get-worker-changes) | Retrieve details for a single change event using its event ID. |

### Suggested workflow

1.  [Fetch worker change fields](https://developer.rippling.com/documentation/rest-api/reference/list-worker-change-fields) to see which worker fields can show up in change events, including each field’s name, type, and category.
2.  [Poll for new events](https://developer.rippling.com/documentation/rest-api/reference/list-worker-changes) as they happen. Narrow the list by when the change was saved (`applied_on`), which worker it affects (`worker_id`), the type of event (`event_type`), or a specific field (`field_key`).
3.  [Fetch details on a specific event](https://developer.rippling.com/documentation/rest-api/reference/get-worker-changes) when you already have a change event `id` and need additional details on the event.

* * *

## Requirements

-   The Rippling API SKU
-   The **Worker Changes API** entitlement enabled. Work with your Rippling Technical Account Manager on this.
-   An API token with the following scopes:
    -   `worker-changes.read` to list worker changes
    -   `worker-change-fields.read` to list worker change fields

* * *

## Fetch

### Worker change fields

Use [GET List worker change fields](https://developer.rippling.com/documentation/rest-api/reference/list-worker-change-fields) to return the available fields (`field_key`) that can appear on worker change events.

_Request:_

```json
curl -X GET "https://rest.ripplingapis.com/worker-change-fields/" \
  -H "Authorization: Bearer REDACTED" \
  -H "Accept: application/json"
```

_Response:_

```json
{
  "results": [
    {
      "field_key": "title",
      "field_display_name": "Title",
      "category": "JOB",
      "value_type": "STRING"
    },
    {
      "field_key": "compensation.base_salary",
      "field_display_name": "Base salary",
      "category": "COMPENSATION",
      "value_type": "CURRENCY"
    }
  ],
  "next_link": null
}
```

| Response field | Description |
| --- | --- |
| `results` | Array of worker change fields. |
| `results[].field_key` | Field key. Use it in `filter=field_key eq '...'` on list worker changes. |
| `results[].field_display_name` | UI label for the field. |
| `results[].category` | High-level grouping for the field: `PERSONAL`, `JOB`, `COMPENSATION`, `BENEFITS`, `CUSTOM`, or `COUNTRY_SPECIFIC`. |
| `results[].value_type` | Value type of the field: `STRING`, `NUMBER`, `BOOLEAN`, `DATE`, `DATETIME`, `CURRENCY`, `ENUM`, or `REFERENCE`. |

### Worker changes

Call [GET List worker changes](https://developer.rippling.com/documentation/rest-api/reference/list-worker-changes) to return a paginated list of all worker changes.

_Request:_

```json
curl -X GET "https://rest.ripplingapis.com/worker-changes/" \
  -H "Authorization: Bearer REDACTED" \
  -H "Accept: application/json"
```

_Response:_

```json
{
  "results": [
    {
      "id": "wc_3b91d04a",
      "created_at": "2026-08-10T14:22:03.000Z",
      "updated_at": "2026-08-10T14:22:03.000Z",
      "worker_id": "58c99d64ea8b383e08da7e22",
      "changed_by_id": null,
      "applied_on": "2026-08-10T14:22:03.000Z",
      "effective_on": "2026-08-10T14:22:03.000Z",
      "event_type": "HIRE",
      "changes": [
        {
          "field_key": "work_email",
          "field_display_name": "Work email",
          "value_type": "STRING",
          "display_type": "VISIBLE",
          "from_value": null,
          "to_value": "jordan.lee@acme.com"
        }
      ]
    }
  ],
  "next_link": null
}
```

| Response field | Description |
| --- | --- |
| `results` | Array of worker change events. |
| `results[].id` | Identifier of the change event. |
| `results[].created_at` | Record creation date. |
| `results[].updated_at` | Record update date. |
| `results[].referenced_transaction_id` | For amendments or undos, the ID of the worker-change event being modified. |
| `results[].worker_id` | The worker affected by this change. |
| `results[].worker` | The affected worker. Returned only when `expand=worker` is requested. Includes terminated employees. |
| `results[].changed_by_id` | User who made the change. Null for system-initiated events. |
| `results[].changed_by` | The user as a worker. Returned only when `expand=changed_by`. |
| `results[].applied_on` | When the change was applied, in UTC. For changes that went through approval, this is the approval time. |
| `results[].effective_on` | When the change is true in the business domain, in UTC. It can be in the past, present, or future, and is independent of `applied_on`. |
| `results[].event_type` | Lifecycle event type: `HIRE`, `CHANGE`, `SCHEDULED_CHANGE`, `OFFBOARD`, `SCHEDULED_OFFBOARD`, `IMPORT`, `UNDO`, or `EFFECTIVE_DATE_AMENDMENT`. `CHANGE` is the catch-all for non-lifecycle field edits. |
| `results[].import_type` | `INITIAL` or `HISTORICAL`. Set only when `event_type` is `IMPORT`. |
| `results[].reason_code` | Structured transition reason, such as `PROMOTION` or `MARKET_ADJUSTMENT`. Null when the company has not configured a reason or the change did not use one. |
| `results[].changes` | Field-level changes captured by this event. A field the caller cannot read is returned as `REDACTED` so the change is still visible. Events whose changed fields are all invisible to the caller are omitted. |
| `results[].changes[].field_key` | Field key. |
| `results[].changes[].field_display_name` | UI label for the field. |
| `results[].changes[].value_type` | Value type of the field: `STRING`, `NUMBER`, `BOOLEAN`, `DATE`, `DATETIME`, `CURRENCY`, `ENUM`, or `REFERENCE`. |
| `results[].changes[].display_type` | `VISIBLE` or `REDACTED`. `REDACTED` means the caller cannot read this field. `from_value` and `to_value` are null, and the entry still shows that a change occurred. |
| `results[].changes[].from_value` | Value before the change, as a display string. Null when `display_type` is `REDACTED`. |
| `results[].changes[].to_value` | Value after the change, as a display string. Null when `display_type` is `REDACTED`. |

Optionally filter [GET List worker changes](https://developer.rippling.com/documentation/rest-api/reference/list-worker-changes) with one of the filterable fields. The below example filters for title changes, but the `changes` array will still list any other fields updated in that same action.

Spaces and quotes must be URL-encoded.

_Request:_

```json
curl -X GET "https://rest.ripplingapis.com/worker-changes/?filter=field_key eq 'title'" \
  -H "Authorization: Bearer REDACTED" \
  -H "Accept: application/json"
```

_Response:_

```json
{
  "results": [
    {
      "id": "wc_8f2a1c9e",
      "created_at": "2026-08-12T18:04:11.000Z",
      "updated_at": "2026-08-12T18:04:11.000Z",
      "worker_id": "58c99d64ea8b383e08da7e16",
      "changed_by_id": "58c99d64ea8b383e08da7e99",
      "applied_on": "2026-08-12T18:04:11.000Z",
      "effective_on": "2026-09-01T00:00:00.000Z",
      "event_type": "CHANGE",
      "changes": [
        {
          "field_key": "title",
          "field_display_name": "Title",
          "value_type": "STRING",
          "display_type": "VISIBLE",
          "from_value": "Software Engineer",
          "to_value": "Senior Software Engineer"
        }
      ]
    }
  ],
  "next_link": null
}
```

Use [GET Retrieve a specific worker change](https://developer.rippling.com/documentation/rest-api/reference/get-worker-changes) to return a specific change event. Requires the `id` of the change event from [GET List worker changes](https://developer.rippling.com/documentation/rest-api/reference/list-worker-changes).

_Request:_

```json
curl -X GET "https://rest.ripplingapis.com/worker-changes/wc_8f2a1c9e/" \
  -H "Authorization: Bearer REDACTED" \
  -H "Accept: application/json"
```

_Response:_

```json
{
  "id": "wc_8f2a1c9e",
  "created_at": "2026-08-12T18:04:11.000Z",
  "updated_at": "2026-08-12T18:04:11.000Z",
  "worker_id": "58c99d64ea8b383e08da7e16",
  "changed_by_id": "58c99d64ea8b383e08da7e99",
  "applied_on": "2026-08-12T18:04:11.000Z",
  "effective_on": "2026-09-01T00:00:00.000Z",
  "event_type": "CHANGE",
  "changes": [
    {
      "field_key": "title",
      "field_display_name": "Title",
      "value_type": "STRING",
      "display_type": "VISIBLE",
      "from_value": "Software Engineer",
      "to_value": "Senior Software Engineer"
    }
  ]
}
```

* * *

## FAQs

**Is the `id` in [GET Retrieve a specific worker change](https://developer.rippling.com/documentation/rest-api/reference/get-worker-changes) the worker ID?**

No, it is the **change event ID**. To query all events for a specific worker, use [GET List worker changes](https://developer.rippling.com/documentation/rest-api/reference/list-worker-changes) with a filter for `worker_id`.

**Why does filtering by a single `field_key` return other fields in the `changes` array?**

Filters match at the event level. If a user updated both title and department in a single save, for example, filtering for title returns the entire event, which includes both changed fields.

**Why is `display_type` returning as `REDACTED`?**

If the API token owner lacks permission to view a specific field, the event is still returned to notify you that a change occurred, but sensitive values are hidden (for example, `display_type: REDACTED` or values set to `null`).

**What does `changed_by_id: null` mean?**

The change was initiated by the system as opposed to modified by a Rippling user.

**How are `field_key` values named?**

For field key details, use the response from [GET List worker change fields](https://developer.rippling.com/documentation/rest-api/reference/list-worker-change-fields):

-   Public fields use the response name (`title`, `work_email`).
-   Nested fields use dots (`compensation.base_salary`).
-   Custom fields use `custom_fields.<custom_field_id>`.
-   Country-specific fields use `country_fields.<field_name>`.

**Does `expand=worker` show the worker at the time of the change?**

No, `expand=worker` and `expand=changed_by` return the current **Worker object** (including terminated workers), as opposed to detail of the date of change.

**What do the `event_type` values mean?**

| Value | Definition |
| --- | --- |
| `HIRE` | Worker created. |
| `CHANGE` | Field edits. |
| `SCHEDULED_CHANGE` | Change that takes effect later. |
| `OFFBOARD` | Termination applied. |
| `SCHEDULED_OFFBOARD` | Future offboard. |
| `IMPORT` | Census or historical import (`import_type` is `INITIAL` or `HISTORICAL`). |
| `UNDO` | Reversal of a prior event. |
| `EFFECTIVE_DATE_AMENDMENT` | Effective date of a prior event was corrected. |

* * *

## See also

-   [Get started with the HRIS API](https://developer.rippling.com/documentation/rest-api/guides/hris-getting-started)
-   [Worker and user field access](https://developer.rippling.com/documentation/rest-api/guides/worker-field-access)
-   [API tokens and permissions](https://developer.rippling.com/documentation/rest-api/essentials/api-tokens)

Source: https://developer.rippling.com/documentation/rest-api/guides/worker-changes

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Public pages have a Markdown version at the same URL with .md added.