For AI agents: an index of this documentation is at https://developer.rippling.com/llms.txt. Public pages have a Markdown version at the same URL with .md added.

Skip to main content
Beta

View worker changes

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

Use with AI:Rippling AI ChatGPT Claude Cursor

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_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​

EndpointDescription
GET List worker change fieldsRetrieve the full catalog of trackable fields, data types, and categories.
GET List worker changesFetch a paginated, filterable feed of worker profile change events.
GET Retrieve a specific worker changeRetrieve details for a single change event using its event ID.

Suggested workflow​

  1. Fetch 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 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 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 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 fieldDescription
resultsArray of worker change fields.
results[].field_keyField key. Use it in filter=field_key eq '...' on list worker changes.
results[].field_display_nameUI label for the field.
results[].categoryHigh-level grouping for the field: PERSONAL, JOB, COMPENSATION, BENEFITS, CUSTOM, or COUNTRY_SPECIFIC.
results[].value_typeValue 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 fieldDescription
resultsArray of worker change events.
results[].idIdentifier of the change event.
results[].created_atRecord creation date.
results[].updated_atRecord update date.
results[].referenced_transaction_idFor amendments or undos, the ID of the worker-change event being modified.
results[].worker_idThe worker affected by this change.
results[].workerThe affected worker. Returned only when expand=worker is requested. Includes terminated employees.
results[].changed_by_idUser who made the change. Null for system-initiated events.
results[].changed_byThe user as a worker. Returned only when expand=changed_by.
results[].applied_onWhen the change was applied, in UTC. For changes that went through approval, this is the approval time.
results[].effective_onWhen 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_typeLifecycle 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_typeINITIAL or HISTORICAL. Set only when event_type is IMPORT.
results[].reason_codeStructured 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[].changesField-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_keyField key.
results[].changes[].field_display_nameUI label for the field.
results[].changes[].value_typeValue type of the field: STRING, NUMBER, BOOLEAN, DATE, DATETIME, CURRENCY, ENUM, or REFERENCE.
results[].changes[].display_typeVISIBLE 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_valueValue before the change, as a display string. Null when display_type is REDACTED.
results[].changes[].to_valueValue 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?

ValueDefinition
HIREWorker created.
CHANGEField edits.
SCHEDULED_CHANGEChange that takes effect later.
OFFBOARDTermination applied.
SCHEDULED_OFFBOARDFuture offboard.
IMPORTCensus or historical import (import_type is INITIAL or HISTORICAL).
UNDOReversal of a prior event.
EFFECTIVE_DATE_AMENDMENTEffective date of a prior event was corrected.

See also​