BAbamboohr
Time Off
Public API

Update Employee Time Off Policy Assignment

Changed on

Updates one of an employee's time off policy assignments using JSON Merge Patch semantics: a field left out of the body keeps its current value, and at least one of policyId and effectiveDate must be present. policyId reassigns the employee to another policy in the same time off category; reassigning to a policy in a different category is rejected, since that is an assignment for the other category and is created with POST. effectiveDate moves the date the assignment takes effect (the accrual basis date for accruing policies); it must not precede the employee's hire date, and on an assignment that has already ended it must not pass the end date. endDate is server managed and not accepted. The change is recorded the way the admin UI records it: the addressed assignment is kept as an audit copy with status SUPERSEDED and a new assignment carrying the requested policy and effective date takes its place, so the response's id differs from assignmentId whenever something changed. The superseded assignment keeps its own dates; it is an audit copy. The employee holds at most one assignment per category at any point in time and this call keeps that true: an assignment in the category that starts on or after the new effective date and no later than this assignment's end date is archived (no longer in effect, kept as history, whether or not it had already taken effect), and the assignment that preceded this one is re-ended at the day before the new effective date. Assignments that start after this one ends are not affected. Everything the call changed, the superseded assignment included, is returned in supersededAssignments in its post-write state; archived assignments are not listed anywhere else. Accruals for the category are recalculated from the earliest date the change affects. A body whose values equal the assignment's current values would change nothing and is refused with 409, as on assign. Accepts both application/merge-patch+json and application/json.

OAuth Scopes: time_off:policies.write

patch/api/v1/employees/{employeeId}/time-off/policies/{assignmentId}

Request

Path parameters

employeeIdinteger required

The employee ID.

assignmentIdinteger required

The ID of the active policy assignment to update, as returned by the list endpoint.

Request body

policyIdinteger

The id of the time off policy to reassign the employee to. Must be an existing, non-deleted policy in the same time off category as the assignment being updated. The assignment keeps its effective date unless effectiveDate is supplied too, so the employee's history for the category is recalculated under the new policy from that date.

effectiveDatestring date

The new date the assignment takes effect, in ISO 8601 format (YYYY-MM-DD). For accruing policies this is the accrual basis date. Must not precede the employee's hire date, and on an assignment that has already ended must not pass its end date.

Example request

{
  "policyId": 15,
  "effectiveDate": "2026-10-01"
}

Response

The assignment as it is after the update, under a new id, with supersededAssignments listing every assignment in the same category the write changed: the addressed assignment with status SUPERSEDED and its original dates, any re-ended preceding assignment with status ACTIVE and its new endDate, and any archived scheduled assignment with status ARCHIVED. Never empty: it always carries at least the superseded addressed assignment.

idinteger

The unique identifier for the policy assignment.

employeeIdinteger

The id of the employee the policy is assigned to.

policyIdinteger

The id of the assigned time off policy.

categoryIdinteger

The id of the time off category the assigned policy belongs to. Denormalized so callers do not need a second request to resolve the policy.

effectiveDatestring date nullable

The date the assignment takes effect, in ISO 8601 format (YYYY-MM-DD). For accruing policies this is the accrual basis date.

endDatestring date nullable

The date the assignment ends, in ISO 8601 format (YYYY-MM-DD). Null when the assignment is open ended. Read-only; the server manages it when a successor assignment supersedes this one.

createdAtstring date-time nullable

UTC timestamp when the assignment was created.

updatedAtstring date-time nullable

UTC timestamp when the assignment was last updated. Null when the assignment has never been updated.

status'ACTIVE' | 'ARCHIVED' | 'SUPERSEDED'

The assignment's lifecycle state. ACTIVE assignments are the ones the list endpoint returns, including those whose endDate has passed: an ended assignment is still the record of the period it covered. ARCHIVED means the assignment is no longer in effect for any date: a later write starting on or before its effective date replaced or cancelled it, whether or not it had already taken effect. It is kept as history and never returns to the list. SUPERSEDED is the pre-change snapshot kept when an assignment is unassigned or its date or policy is changed; the successor row carries the change. Only ACTIVE appears in list responses; the other two appear inside supersededAssignments on the write response that produced them.

Example response

{
  "id": 821,
  "employeeId": 40341,
  "policyId": 15,
  "categoryId": 64,
  "effectiveDate": "2022-05-02",
  "createdAt": "2025-05-27T22:34:07Z",
  "updatedAt": "2025-05-27T22:34:07Z",
  "status": "ACTIVE",
  "supersededAssignments": [
    {
      "id": 821,
      "employeeId": 40341,
      "policyId": 15,
      "categoryId": 64,
      "effectiveDate": "2022-05-02",
      "createdAt": "2025-05-27T22:34:07Z",
      "updatedAt": "2025-05-27T22:34:07Z",
      "status": "ACTIVE"
    }
  ]
}

Changes