BAbamboohr
Time Off
Public API

Assign Employee Time Off Policy

Changed on

Assigns a time off policy to an employee, effective from effectiveDate. An employee holds at most one assignment per time off category at any point in time, and this call keeps that true rather than refusing: an assignment in the same category that is in force on effectiveDate is end-dated to the day before, and any assignment in that category starting on or after effectiveDate, scheduled or already in effect, is archived: it is no longer in effect for any date and is kept as history. Neither is an error: both changed assignments are returned in the response's supersededAssignments, the end-dated one with its new endDate and status ACTIVE, the archived ones with status ARCHIVED. A subsequent GET of the employee's policies shows the end-dated assignment; archived assignments are not listed anywhere else, so this response is the one place a caller sees them. The one conflict is assigning the policy the employee already holds with the same effectiveDate, which would change nothing and returns 409; that applies to any active assignment on that policy and date, scheduled or already ended, not only the one in force today. effectiveDate is required for every policy type and must not precede the employee's hire date. endDate is not accepted: new assignments are always open ended, and are ended later by unassigning or by a successor assignment. Accruals for the category are recalculated from the effective date.

OAuth Scopes: time_off:policies.write

post/api/v1/employees/{employeeId}/time-off/policies

Request

Path parameters

employeeIdinteger required

The employee ID.

Request body

policyIdinteger required

The id of the time off policy to assign. Must be an existing, non-deleted policy.

effectiveDatestring date required

The 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. Required for every policy type, including discretionary and manual policies.

Example request

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

Response

The created assignment, with supersededAssignments listing every assignment in the same category the write end-dated or archived (empty when nothing collided).

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