---
title: "Bulk Create Company Holidays"
method: POST
path: "/api/v1/holidays/bulk-insert"
tags: ["Holidays", "Public API"]
---

# Bulk Create Company Holidays

`POST /api/v1/holidays/bulk-insert`

## Request

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

Creates multiple company holidays in one synchronous call. Each record follows the single-create semantics: it may be fully-specified or carry a globalHolidayUuid that seeds name, dates, and countries from the global catalog entry (mix-and-match within the same request). Records are processed in request order.

OAuth Scopes: holidays.write

## Query parameters

- `atomic` boolean
- `returnRecords` boolean

## Request body

- HolidayCreateCompanyHolidayRequestV1[]
  - `globalHolidayUuid` string, uuid, nullable: UUID of a global catalog entry. When supplied, the server seeds name, startDate, endDate, and countryCodes from the catalog entry; partner-supplied values override the catalog defaults.
  - `name` string, nullable: The name of the holiday. Required when globalHolidayUuid is not supplied. 1-255 characters.
  - `startDate` string, date, nullable: The start date of the holiday. Required when globalHolidayUuid is not supplied.
  - `endDate` string, date, nullable: The end date of the holiday. Null means a single-day holiday. Must be greater than or equal to startDate.
  - `isPublic` boolean: Whether the holiday is visible to all employees on calendars, independent of audience. Defaults to true.
  - `countryCodes` string[], nullable: Country filter as ISO 3166-1 alpha-2 codes. An empty array means no country filter. When omitted on a catalog-referenced create, the catalog entry's country is used.
  - `audience` HolidayCompanyHolidayAudienceV1, required: Defines which employees a company holiday applies to
    - `mode` 'ALL_EMPLOYEES' | 'FILTERED' | 'SPECIFIC_EMPLOYEES': How the holiday audience is determined
    - `filterListValueIds` integer[]: List-value IDs that filter the audience. Only populated in FILTERED mode.
    - `specificEmployeeIds` integer[]: Employee IDs that define the audience. Only populated in SPECIFIC_EMPLOYEES mode.
    - `additionalEmployeeIds` integer[]: Employee IDs explicitly included on top of the mode's default audience.
    - `exemptEmployeeIds` integer[]: Employee IDs explicitly excluded from the mode's default audience.
  - `holidayPay` HolidayCompanyHolidayPayV1, nullable: Pay treatment for a company holiday
    - `mode` 'HOURS_BY_STATUS' | 'MULTIPLIER': How holiday pay is calculated
    - `defaultHours` string, nullable: Catch-all hours applied to employment statuses without an override. Only populated in HOURS_BY_STATUS mode.
    - `hoursByEmploymentStatus` HolidayCompanyHolidayPayStatusHoursV1[]: Per-employment-status hour overrides. Only populated in HOURS_BY_STATUS mode.
      - `employmentStatusListValueId` integer: List-value ID from the company's Employment Status list
      - `hours` string: Paid hours for the employment status
    - `multiplier` string, nullable: Pay rate multiplier. Only populated in MULTIPLIER mode.

## Response `200`

All records were created successfully.

- HolidayBulkInsertCompanyHolidaysResponseV1: Result envelope for a synchronous bulk-insert of company holidays.
  - `status` 'success' | 'partial_success' | 'failed': Overall batch outcome
  - `operation` string: Operation type for this bulk request
  - `totalRequested` integer: Total number of records in the request
  - `totalProcessed` integer: Total number of records created successfully
  - `failed` integer: Total number of records that failed
  - `errors` HolidayBulkInsertCompanyHolidayErrorV1[]: Per-record problem-details style errors
    - `recordIndex` integer: Zero-based index of the failed record in the request body array
    - `type` string: Problem type URI identifying the error category
    - `title` string: Short, human-readable summary of the problem type
    - `status` integer: HTTP status code the record would have received from the single-create endpoint
    - `detail` string: Human-readable explanation specific to this record failure
    - `code` string: Application-specific error code
  - `records` HolidayBulkInsertCompanyHolidayRecordV1[]: Per-record success results, in request order
    - `id` integer: The ID of the created company holiday
    - `status` string: Per-record operation outcome
    - `httpStatus` integer: HTTP status code representing the per-record result
    - `record` HolidayCompanyHolidayV1: A company holiday
      - `id` integer: The ID of the holiday
      - `name` string: The name of the holiday
      - `startDate` string, date: The start date of the holiday
      - `endDate` string, date, nullable: The end date of the holiday. Null for single-day holidays.
      - `isPublic` boolean: Whether the holiday is visible to all employees on calendars, independent of audience
      - `countryCodes` string[]: Country filter as ISO 3166-1 alpha-2 codes. Empty means no country filter.
      - `audience` HolidayCompanyHolidayAudienceV1: Defines which employees a company holiday applies to
        - `mode` 'ALL_EMPLOYEES' | 'FILTERED' | 'SPECIFIC_EMPLOYEES': How the holiday audience is determined
        - `filterListValueIds` integer[]: List-value IDs that filter the audience. Only populated in FILTERED mode.
        - `specificEmployeeIds` integer[]: Employee IDs that define the audience. Only populated in SPECIFIC_EMPLOYEES mode.
        - `additionalEmployeeIds` integer[]: Employee IDs explicitly included on top of the mode's default audience.
        - `exemptEmployeeIds` integer[]: Employee IDs explicitly excluded from the mode's default audience.
      - `holidayPay` HolidayCompanyHolidayPayV1, nullable: Pay treatment for a company holiday
        - `mode` 'HOURS_BY_STATUS' | 'MULTIPLIER': How holiday pay is calculated
        - `defaultHours` string, nullable: Catch-all hours applied to employment statuses without an override. Only populated in HOURS_BY_STATUS mode.
        - `hoursByEmploymentStatus` HolidayCompanyHolidayPayStatusHoursV1[]: Per-employment-status hour overrides. Only populated in HOURS_BY_STATUS mode.
          - `employmentStatusListValueId` integer: List-value ID from the company's Employment Status list
          - `hours` string: Paid hours for the employment status
        - `multiplier` string, nullable: Pay rate multiplier. Only populated in MULTIPLIER mode.
      - `globalHolidayUuid` string, uuid, nullable: UUID of the global catalog entry this holiday was sourced from. Null for custom holidays.
      - `createdAt` string, date-time: ISO 8601 timestamp when the holiday was created
      - `updatedAt` string, date-time: ISO 8601 timestamp when the holiday was last updated
      - `deletedAt` string, date-time, nullable: ISO 8601 timestamp when the holiday was soft-deleted. Null for active holidays.

## Other responses

- `207`: Partial success (non-atomic mode): some records were created and some failed. Per-record errors carry the recordIndex of the failing record in the request body.
- `400`: Malformed request body: not a JSON array, or a record is not a JSON object.
- `401`: Unauthorized. Missing or invalid authentication.
- `403`: Forbidden. Insufficient permissions.
- `422`: Nothing was created. Request-level validation errors (empty array, more than 100 records, an invalid atomic/returnRecords parameter) return a problem-details body. Full batch failures — an atomic abort or a non-atomic batch in which every record failed — return the bulk envelope with status failed and per-record errors.

## Changes

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

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/holidays/bulk-insert/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)