# Business Hours & Business Holiday List API V3 — Developer Guide

- **Applies to:** Sprinklr Business Hours & Business Holiday APIs V3
- **V2 API reference:** [Business Hours and Holiday Lists | Sprinklr Developer Portal](https://dev.sprinklr.com/business-hours-and-holiday-lists)


## 1. Overview

The **Business Hours API** allows you to configure working hours and associate them with holiday lists.
The **Business Holiday List API** allows you to define and manage holidays that can be linked to business hours.

### Related Knowledge Base Article

**[Create Business Hours and Holiday Lists](https://www.sprinklr.com/help/categories/business-hours/67d152b7540cf66736ba6c0f)**

These endpoints replace the V2 paths with simplified V3 resources:

| Operation | Method | Path |
|  --- | --- | --- |
| Create Business Hours | `POST` | `/api/v3/businessHours` |
| Update Business Hours | `PUT` | `/api/v3/businessHours?id={id}` |
| Search Business Hours | `POST` | `/api/v3/search/businessHours` |
| Fetch Business Hour by Id | `GET` | `/api/v3/businessHours?id={id}` |
| Delete Business Hour | `DELETE` | `/api/v3/businessHours/{id}` |
| Create Holiday List | `POST` | `/api/v3/businessHolidays` |
| Update Holiday List | `PUT` | `/api/v3/businessHolidays?id={id}` |
| Fetch Holiday List by Id | `GET` | `/api/v3/businessHolidays?id={id}` |
| Delete Holiday List | `DELETE` | `/api/v3/businessHolidays?id={id}` |


## 2. Base URLs and environments

All API calls are sent to the production endpoint:

```
https://api3.sprinklr.com/{env}/api/v3
```

So the Business Hours and Holiday Lists resource in production are:

- **Business Hours Resource**


```
https://api3.sprinklr.com/{env}/api/v3/businessHours
```

- **Business Holiday Lists Resource**


```
https://api3.sprinklr.com/{env}/api/v3/businessHolidays
```

Replace `{env}` with your assigned environment identifier (`prod0`, `prod2`, `prod11`, etc.).

## 3. Authentication and common headers

All API calls are authenticated with OAuth 2.0.
See API Overview for portal registration, API key and secret generation, and the Authorize flow.

| Header | Value | Purpose | Required on |
|  --- | --- | --- | --- |
| Authorization | Bearer {{accessToken}} | Authenticates the user with the server | All requests |
| Key | {{apiKey}} | Authenticates the application with server | All requests |
| Content-Type | application/json | Declares the request body media type | All requests |
| Accept | application/json | Declares the acceptable response type | All requests |


## 4. Business Hours Operations

### 4.1 Create Business Hours

**`POST /api/v3/businessHours`**

Creates a business hours configuration.

**Request parameters:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| name | Required | Name of the business hours configuration. | String |
| description | Optional | Description of the configuration. | String |
| timeZone | Required | Time zone of the configuration. | String |
| businessHolidayLists | Optional | Array of holiday list IDs. | Array |
| daySchedules | Required | Array of daily schedules. | Array |


**Day Schedule Object:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| schedulingDay | Required | Day of the week (MONDAY–SUNDAY). | String |
| timeRange | Optional | Array of time ranges. | Array |
| timeRange.from | Optional | Start time in minutes after midnight. | Int |
| timeRange.upto | Optional | End time in minutes after midnight. | Int |
| timeRange.timeUnit | Optional | Unit of time measurement. Supported: MINUTES. | String |


**Example — Request**

```bash
curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/businessHours' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'api-key: {API KEY}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Business Hours Configuration New",
  "timeZone": "Asia/Kabul",
  "daySchedules": [
    { "schedulingDay": "MONDAY", "timeRange": [ { "from": 210, "upto": 420, "timeUnit": "MINUTES" } ] }
  ]
}'
```

### 4.2 Update Business Hours

**`PUT /api/v3/businessHours?id={id}`**

Updates an existing business hours configuration.

**Request parameters:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| id | Required | ID of the business hours configuration. Obtain from the Create Business Hour API response. | String |
| name | Required | Name of the business hours configuration. | String |
| description | Optional | Description of the business hours configuration. | String |
| timeZone | Required | Time zone of the business hours configuration. | String |
| businessHolidayLists | Optional | Array of business holiday list IDs. Obtain from the Create Business Holiday List API. | Array |
| daySchedules | Required | Array specifying work time slots for each day of the week. | Array |


**Day Schedule Object:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| schedulingDay | Required | Day of the week (MONDAY–SUNDAY). | String |
| timeRange | Optional | Array of time ranges. | Array |
| timeRange.from | Optional | Start time in minutes after midnight (e.g., 210 = 3:30 AM). | Int |
| timeRange.upto | Optional | End time in minutes after midnight (e.g., 450 = 7:30 AM). | Int |
| timeRange.timeUnit | Optional | Unit of time measurement. Supported: MINUTES. | String |


**Example — Request**

```bash
curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/businessHours?id=6a90a5a5bd04dae869455fc5' \
--header 'Authorization: Bearer {Enter Your Access Token}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Business Hours Configuration New",
  "description": "Testing Update",
  "timeZone": "Asia/Kabul",
  "daySchedules": [
    {
      "schedulingDay": "MONDAY",
      "timeRange": [ { "from": 210, "upto": 420, "timeUnit": "MINUTES" } ]
    },
    {
      "schedulingDay": "TUESDAY",
      "timeRange": [ { "from": 210, "upto": 420, "timeUnit": "MINUTES" } ]
    },
    {
      "schedulingDay": "WEDNESDAY",
      "timeRange": [ { "from": 210, "upto": 420, "timeUnit": "MINUTES" } ]
    },
    {
      "schedulingDay": "THURSDAY",
      "timeRange": [ { "from": 210, "upto": 420, "timeUnit": "MINUTES" } ]
    },
    {
      "schedulingDay": "FRIDAY",
      "timeRange": [ { "from": 210, "upto": 420, "timeUnit": "MINUTES" } ]
    }
  ],
  "businessHolidayLists": [ "68677075c54b2035433195a7" ]
}'
```

### 4.3 Search Business Hours

**`POST /api/v3/search/businessHours`**

Retrieves details of all business hours configurations created in Sprinklr.

**Request parameters:**

| Parameter | Sub‑parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- | --- |
| filter |  | Optional | Defines filter conditions for searching business hours. Supports logical operators (AND, OR) and filter types (IN, EQUALS, etc.). | Object |
|  | type | Optional | Logical operator for combining filters. | String |
|  | filters | Optional | Array of filter conditions. Each filter object contains its own parameters such as type, key, and values. | Array |
| sorts |  | Optional | Specifies sorting criteria for results. Example: sort by modifiedTime in descending order. | Array |
|  | key | Optional | Field to sort by. | String |
|  | order | Optional | Sorting order (ASC, DESC). | String |
| page |  | Optional | Defines pagination details such as page size. | Object |
|  | size | Optional | Maximum number of items to return per page. | Number |


**Filters Array Object:**

| Sub‑parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| type | Optional | Defines the filter type. Example: IN, EQUALS. | String |
| key | Optional | Field to filter on. Example: name, id. | String |
| values | Optional | Values to match against the specified key. Example: ["Business Hours Configuration New"]. | Array |


**Example — Request**

```bash
curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/search/businessHours' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'api-key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "filter": {
    "type": "AND",
    "filters": [
      {
        "type": "IN",
        "key": "name",
        "values": [ "Business Hours Configuration New" ]
      }
    ]
  },
  "sorts": [
    { "key": "modifiedTime", "order": "DESC" }
  ],
  "page": { "size": 20 }
}'
```

### 4.4 Fetch Business Hour by Id

**`GET /api/v3/businessHours?id={id}`**

Retrieves a specific business hours configuration in Sprinklr using its unique ID.
The ID is generated when the configuration is created.

**Request parameters:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| id | Required | ID of the business hours configuration. Obtain from the Create Business Hour API response. | String |


**Example — Request**

```bash
curl --location --request GET 'https://api3.sprinklr.com/{env}/api/v3/businessHours?id=6a90a5a5bd04dae869455fc5' \
--header 'Authorization: Bearer {Enter Your Access Token}' \
--header 'api-key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
```

### 4.5 Delete Business Hour

**`DELETE /api/v3/businessHours/{business_hours_id}`**

Deletes a specific business hours configuration in Sprinklr using its unique ID.
The ID is generated when the configuration is created.

**Path parameters:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| {business_hours_id} | Required | ID of the business hours configuration. Obtain from the Create Business Hour API response. | String |


**Example — Request**

```bash
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/businessHours/6a90a5a5bd04dae869455fc5' \
--header 'Authorization: Bearer {Enter Your Access Token}' \
--header 'api-key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
```

## 5. Business Holiday Lists Operations

### 5.1 Create Business Holiday List

**`POST /api/v3/businessHolidays`**

Creates a business holiday list in Sprinklr.

**Request parameters:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| name | Required | Name of the business holiday list configuration. | String |
| timeZone | Required | Time zone of the business holiday list configuration. | String |
| businessHolidays | Required | List of business holidays. At least one holiday must be included. | Array |


**Business Holiday Object:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| title | Optional | Name or title of the holiday. | String |
| allDay | Optional | Indicates whether the holiday lasts all day. | Boolean |
| timeRange | Optional | Array of specific time ranges for partial-day holidays. | Array |
| timeRange.from | Optional | Start time in minutes after midnight (e.g., 210 = 3:30 AM). | Int |
| timeRange.upto | Optional | End time in minutes after midnight (e.g., 450 = 7:30 AM). | Int |
| timeRange.timeUnit | Optional | Unit of time measurement. Supported value: MINUTES. | String |
| date | Required | Date of the holiday in epoch timestamp format (milliseconds). Example: 1744934400000 for 2025-04-18. | Number |


**Example — Request**

```bash
curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/businessHolidays' \
--header 'Authorization: Bearer {Enter Your Access Token}' \
--header 'api-key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "name": "BR Business Holiday List 2",
  "timeZone": "Asia/Dhaka",
  "businessHolidays": [
    { "title": "Good Friday", "allDay": true, "timeRange": [], "date": 1744934400000 },
    { "title": "May Day", "allDay": true, "timeRange": [], "date": 1746345600000 },
    { "title": "Muharram", "allDay": true, "timeRange": [], "date": 1752067200000 },
    { "title": "Independence day", "allDay": true, "timeRange": [], "date": 1755523200000 },
    { "title": "New Holiday", "allDay": true, "timeRange": [], "date": 1755523200000 }
  ]
}'
```

### 5.2 Update Business Holiday List

**`PUT /api/v3/businessHolidays?id={id}`**

Updates an existing business holiday list in Sprinklr.

**Request parameters:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| id | Required | ID of the business holiday list to update. Obtain from the Create Business Holiday List API response. | String |
| name | Required | Name of the business holiday list configuration. | String |
| timeZone | Required | Time zone of the business holiday list configuration. | String |
| businessHolidays | Required | List of business holidays. At least one holiday must be included. | Array |


**Business Holiday Object:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| title | Optional | Name or title of the holiday. | String |
| allDay | Optional | Indicates whether the holiday lasts all day. | Boolean |
| timeRange | Optional | Array of specific time ranges for partial-day holidays. | Array |
| timeRange.from | Optional | Start time in minutes after midnight (e.g., 210 = 3:30 AM). | Int |
| timeRange.upto | Optional | End time in minutes after midnight (e.g., 450 = 7:30 AM). | Int |
| timeRange.timeUnit | Optional | Unit of time measurement. Supported value: MINUTES. | String |
| date | Required | Date of the holiday in epoch timestamp format (milliseconds). Example: 1744934400000 for 2025-04-18. | Number |


**Example — Request**

```bash
curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/businessHolidays?id=6a16bda4b22a98b287ad6a02' \
--header 'Authorization: Bearer {Enter Your Access Token}' \
--header 'api-key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "name": "US Federal Holidays 2025 (Revised)",
  "timeZone": "America/Chicago",
  "businessHolidays": [
    {
      "title": "New Year'\''s Day",
      "date": 1735689600000,
      "allDay": true,
      "timeRange": []
    }
  ]
}'
```

### 5.3 Fetch Business Holiday List by Id

**`GET /api/v3/businessHolidays?id={id}`**

Fetches a business holiday list by its unique ID.
The ID is generated when the holiday list is created.

**Request parameters:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| id | Required | ID of the business holiday list to retrieve. Obtain from the Create Business Holiday List API response. | String |


**Example — Request**

```bash
curl --location --request GET 'https://api3.sprinklr.com/{env}/api/v3/businessHolidays?id=6a910ddfe67b03ffd813b2c7' \
--header 'Authorization: Bearer {Enter Your Access Token}' \
--header 'api-key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data ''
```

### 5.4 Delete Business Holiday List

**`DELETE /api/v3/businessHolidays?id={id}`**

Deletes a business holiday list from Sprinklr using its unique ID.
The ID is generated when the holiday list is created.

**Request parameters:**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| id | Required | ID of the business holiday list to delete. Obtain from the Create Business Holiday List API response. | String |


**Example — Request**

```bash
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/businessHolidays?id=6a910ddfe67b03ffd813b2c7' \
--header 'Authorization: Bearer {Enter Your Access Token}' \
--header 'api-key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
```

## 6. Response format and status codes

All Business Hours and Business Holiday List API responses return a consistent envelope:

```json
{
  "data": Object | Array | String | Boolean,
  "errors": []
}

### 6.1 Envelope Fields

| **Field** | **Type**                        | **Description**                                                                 |
|-----------|---------------------------------|---------------------------------------------------------------------------------|
| data      | Object / Array / String / Boolean | Response payload. <br>Examples: configuration object (JSON), `true` for update success, or array of holiday entries. |
| errors    | Array                           | List of error messages (empty if none).                                         |

### Example — Create Business Hours Response

```json
{
  "data": {
    "id": "6a90a5a5bd04dae869455fc5",
    "name": "Business Hours Configuration New",
    "timeZone": "Asia/Kabul",
    "daySchedules": [ ... ],
    "createdTime": "Aug 27, 2026, 09:01:25 PM",
    "modifiedTime": "Aug 27, 2026, 09:01:25 PM"
  },
  "errors": []
}
```

### Example — Update Business Hours Response

```json
{
  "data": true,
  "errors": []
}
```

### Example — Delete Business Hours Response

```json
204 No Content
```

### Example — Create Business Holiday List Response

```json
{
  "data": {
    "id": "6a910ddfe67b03ffd813b2c7",
    "name": "BR Business Holiday List 2",
    "timeZone": "Asia/Dhaka",
    "businessHolidays": [ ... ],
    "createdTime": "Aug 28, 2026, 04:26:07 AM",
    "modifiedTime": "Aug 28, 2026, 04:26:07 AM"
  },
  "errors": []
}
```

### 6.2 Response codes

| **HTTP Code** | **Scenario** | **Description** |
|  --- | --- | --- |
| 200 OK | Success | Operation executed successfully; resource returned |
| 204 No Content | Success (Update/Delete) | Resource updated or deleted successfully |
| 400 Bad Request | Invalid Parameters | Missing required parameters or invalid parameter combinations |
| 401 Unauthorized | Authentication Failed | Invalid or missing Authorization token |
| 403 Forbidden | Insufficient Permissions | User lacks permission to perform the operation |
| 404 Not Found | Resource Missing | Business Hours or Holiday List not found |
| 500 Internal Server Error | Server Error | Unexpected server-side error occurred |


## 7. Migration from V2 to V3

The Business Hours and Business Holiday List APIs have been redesigned in **V3** for consistency, clarity, and improved lifecycle control.
Below is a comparison of **V2 vs V3 endpoints and behavior**:

| **Operation** | **V2 Endpoint** | **V3 Endpoint** | **Key Differences** |
|  --- | --- | --- | --- |
| Create Business Hours | `POST /api/v2/business-hours` | `POST /api/v3/businessHours` | V2 used `/business-hours`; V3 uses `/businessHours` with stricter schema validation. |
| Update Business Hours | `POST /api/v2/business-hours` (with `id` in body) | `PUT /api/v3/businessHours?id={id}` | V2 required `id` in request body; V3 uses query parameter `id` with proper REST semantics. |
| Fetch Business Hours (by Id) | `GET /api/v2/business-hours/id/{id}` | `GET /api/v3/businessHours?id={id}` | V2 used `/id/{id}` path; V3 uses query parameter `id`. |
| Search Business Hours | `GET /api/v2/business-hours?page={page}&size={size}` | `POST /api/v3/search/businessHours` with `page.size` and filter criteria. | V2 used query parameters; V3 uses structured search request body with filters/pagination. |
| Delete Business Hours | `DELETE /api/v2/business-hours/{id}` | `DELETE /api/v3/businessHours/{id}` | V2 used path parameter; V3 continues with path parameter but enforces stricter validation. |
| Create Holiday List | `POST /api/v2/business-holidays` | `POST /api/v3/businessHolidays` | V2 used `/business-holidays`; V3 uses `/businessHolidays` with stricter schema validation. |
| Update Holiday List | `POST /api/v2/business-holidays` (with `id` in body) | `PUT /api/v3/businessHolidays?id={id}` | V2 required `id` in request body; V3 uses query parameter `id` with proper REST semantics. |
| Fetch Holiday List (by Id) | `GET /api/v2/business-holidays/id/{id}` | `GET /api/v3/businessHolidays?id={id}` | V2 used `/id/{id}` path; V3 uses query parameter `id`. |
| Fetch Holiday List (by Name) | `GET /api/v2/business-holidays/by-name?name={name}` | *Not supported directly* — use `POST /api/v3/search/businessHolidays` with filter on `name`. | V2 had a dedicated endpoint; V3 consolidates search into a flexible filter-based API. |
| Fetch Holiday Lists (Paginated) | `GET /api/v2/business-holidays?page={page}&size={size}` | `POST /api/v3/search/businessHolidays` with `page.size` and filter criteria. | V2 used query parameters; V3 uses structured search request body with pagination. |
| Delete Holiday List | `DELETE /api/v2/business-holidays/{id}` | `DELETE /api/v3/businessHolidays?id={id}` | V2 used path parameter; V3 uses query parameter for deletion. |