---
title: "Create Time Off Category"
method: POST
path: "/api/v1/time-off/categories"
tags: ["Time Off", "Public API"]
---

# Create Time Off Category

`POST /api/v1/time-off/categories`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/time-off/categories`
- Auth: one of:
  - HTTP basic
  - OAuth 2
    - Authorization code: `/authorize.php`
    - Token URL: `/token.php` scopes: `time_off:categories.write`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/time-off/categories/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a time off category. Category names are unique among all of the company's categories, including disabled and deleted ones; a name collision returns a 409 that identifies the conflicting category so the caller can resolve it (for example by choosing a different name).

OAuth Scopes: time_off:categories.write

## Request body

- TimeOffCreateCategoryV1: Data contract for creating a time off category.
  - `name` string, required: The name of the time off category. Must be unique among the company's active categories.
  - `unit` 'HOURS' | 'DAYS', required: The unit of measurement for the time off category.
  - `color` '4AADA4' | '56AFDD' | 'B185DA' | 'E8454D' | 'F96422' | 'EEF448' | '6A6A6A', nullable: The color for the category, as a six character hex code without a leading "#". Must be one of the supported category colors. Omit or send null to use the company color.
  - `icon` string, nullable: The icon for the category. Omit to use the default icon.
  - `paid` boolean: Whether time off in this category is paid.
  - `includeInPayroll` boolean: Whether this category should be included in payroll. Only takes effect when the company has payroll with timecard auto sync enabled; otherwise the created category is not included in payroll.

## Response `201`

The created time off category.

- TimeOffCategoryV1: A category of time off that can be used when requesting time off, such as vacation or sick leave
  - `id` integer: The unique identifier for the time off category.
  - `name` string: The name of the time off category.
  - `unit` 'HOURS' | 'DAYS': The unit of measurement for the time off category, in either days or hours.
  - `color` string, nullable: The color associated with the time off category.
  - `icon` string: The icon representing the time off category.
  - `paid` boolean: Indicates if the time off category is paid.
  - `includeInPayroll` boolean: Indicates if the time off category should be included in payroll.
  - `enabled` boolean: Indicates if the time off category is currently in use. A disabled category is retained for historical records but cannot be selected on new time off requests.
  - `createdAt` string, date-time: UTC timestamp when the time off category was created.
  - `updatedAt` string, date-time, nullable: UTC timestamp when the time off category was last updated.
  - `deletedAt` string, date-time, nullable: UTC timestamp when the time off category was deleted.

## Other responses

- `400`: Malformed request body.
- `401`: Unauthorized. Missing or invalid authentication.
- `403`: Forbidden. The caller may not manage time off categories.
- `409`: A time off category (possibly disabled or deleted) already uses the requested name. The response's conflictingCategory member identifies the category holding it (id, name, enabled, deleted), or is null when it could not be identified.
- `422`: The request body failed validation.

## Changes

- **2026-11-03** `922fc15f43a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/time-off/categories/post.md)

---

[API](https://skmtc.dev/bamboohr/apis/bamboohr-api.md) - [All operations](https://skmtc.dev/bamboohr/apis/bamboohr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bamboohr/apis/bamboohr-api/revisions/922fc15f43a7?raw)