BAbamboohr
Time Off
Public API

Create Time Off Policy

Changed on

Creates a time off policy. Accruing policies include an inlined initial version with milestones; unlimited and manual policies have no version.

OAuth Scopes: time_off:policies.write

post/api/v1/time-off/policies

Request

Request body

namestring required

The name of the time off policy. Must be unique among the category's active policies.

categoryIdinteger required

The id of the time off category this policy belongs to.

type'ACCRUING' | 'UNLIMITED' | 'MANUAL' required

The type of the time off policy.

Example request

{
  "name": "Standard Vacation",
  "categoryId": 22,
  "type": "ACCRUING",
  "version": {
    "effectiveDate": "2026-01-01",
    "rateTransitions": "IMMEDIATELY",
    "firstAccrual": "PRORATE",
    "carryOverYmd": "01-01",
    "milestones": [
      {
        "accrualBeginsType": "IMMEDIATELY",
        "accrualHours": 6.67,
        "accrualInterval": "MONTHLY",
        "maximumHours": 240,
        "maximumCarryOver": 40
      }
    ]
  }
}

Response

The created time off policy, including currentVersion for accruing policies.

idinteger

The unique identifier for the time off policy.

namestring

The name of the time off policy.

categoryIdinteger

The id of the time off category this policy belongs to.

type'ACCRUING' | 'UNLIMITED' | 'MANUAL'

The type of the time off policy.

assignedEmployeeCountinteger

The number of active employees currently assigned to this policy.

createdAtstring date-time

UTC timestamp when the policy was created.

updatedAtstring date-time nullable

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

deletedAtstring date-time nullable

UTC timestamp when the policy was deleted. Always null because deleted policies are excluded from the API.

Example response

{
  "id": 1,
  "name": "Standard Vacation",
  "categoryId": 22,
  "type": "ACCRUING",
  "currentVersion": {
    "id": 1,
    "policyId": 15,
    "effectiveDate": "2026-01-01",
    "status": "ACTIVE",
    "rateTransitions": "IMMEDIATELY",
    "firstAccrual": "PRORATE",
    "carryOverYmd": "01-01",
    "milestones": [
      {
        "id": 1,
        "accrualBeginsType": "IMMEDIATELY",
        "accrualHours": 6.67,
        "accrualInterval": "MONTHLY",
        "maximumHours": 240,
        "maximumCarryOver": 40
      }
    ],
    "createdAt": "2026-01-01T06:00:00Z",
    "updatedAt": "2026-01-02T17:00:00Z"
  },
  "assignedEmployeeCount": 42,
  "createdAt": "2026-01-01T06:00:00Z",
  "updatedAt": "2026-01-02T17:00:00Z"
}

Changes