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 by the compensation
field_keyvalues to keep rewards systems updated with recent and future-dated salary changes. - Audit worker history: Filter events by
worker_idto 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 | Retrieve the full catalog of trackable fields, data types, and categories. |
| GET List worker changes | Fetch a paginated, filterable feed of worker profile change events. |
| GET Retrieve a specific worker change | Retrieve details for a single change event using its event ID. |
Suggested workflow
- Fetch worker change fields to see which worker fields can show up in change events, including each field’s name, type, and category.
- Poll for new events 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). - Fetch details on a specific event when you already have a change event
idand 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.readto list worker changesworker-change-fields.readto list worker change fields
Fetch
Worker change fields
Use GET List worker change fields to return the available fields (field_key) that can appear on worker change events.
Request:
curl -X GET "https://rest.ripplingapis.com/worker-change-fields/" \
-H "Authorization: Bearer REDACTED" \
-H "Accept: application/json"
Response:
{
"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 to return a paginated list of all worker changes.
Request:
curl -X GET "https://rest.ripplingapis.com/worker-changes/" \
-H "Authorization: Bearer REDACTED" \
-H "Accept: application/json"
Response:
{
"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 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:
curl -X GET "https://rest.ripplingapis.com/worker-changes/?filter=field_key eq 'title'" \
-H "Authorization: Bearer REDACTED" \
-H "Accept: application/json"
Response:
{
"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 to return a specific change event. Requires the id of the change event from GET List worker changes.
Request:
curl -X GET "https://rest.ripplingapis.com/worker-changes/wc_8f2a1c9e/" \
-H "Authorization: Bearer REDACTED" \
-H "Accept: application/json"
Response:
{
"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 the worker ID?
No, it is the change event ID. To query all events for a specific worker, use GET 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:
- 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. |