Manage business and shift holidays in Zoho CRM. This API allows you to create, retrieve, update, and delete holidays that affect business hours and shift schedules. Business holidays apply to all users while shift holidays apply to specific shift configurations.
{
"openapi": "3.1.0",
"info": {
"title": "Zoho CRM Holidays API",
"description": "Manage business and shift holidays in Zoho CRM. This API allows you to create, retrieve, update, and delete holidays that affect business hours and shift schedules. Business holidays apply to all users while shift holidays apply to specific shift configurations.",
"version": "8"
},
"servers": [
{
"url": "https://zohoapis.{dc}/crm/{version}",
"description": "API Server URL",
"variables": {
"dc": {
"enum": [
"com",
"eu",
"in",
"cn",
"au"
],
"default": "com",
"description": "API Server URL TLD"
},
"version": {
"enum": [
"v8"
],
"default": "v8",
"description": "API version"
}
}
}
],
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.business_hours.READ",
"ZohoCRM.settings.business_hours.CREATE",
"ZohoCRM.settings.business_hours.UPDATE",
"ZohoCRM.settings.business_hours.DELETE"
]
}
],
"tags": [
{
"name": "Holidays",
"description": "Operations for managing holidays that affect business hours and shift schedules"
}
],
"paths": {
"/settings/holidays": {
"get": {
"tags": [
"Holidays"
],
"summary": "Retrieve holidays",
"description": "Retrieves a list of holidays filtered by year, type (business or shift), and shift ID. Business holidays apply organization-wide, while shift holidays are specific to configured shifts. Returns paginated results with metadata.",
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.business_hours.READ"
]
}
],
"operationId": "getHolidays",
"parameters": [
{
"$ref": "#/components/parameters/Year"
},
{
"$ref": "#/components/parameters/Type"
},
{
"$ref": "#/components/parameters/ShiftId"
}
],
"responses": {
"200": {
"description": "Success - Returns a paginated list of holidays matching the specified filter criteria",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"holidays": {
"type": "array",
"description": "Array of holiday objects matching the filter criteria",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the holiday. Cannot contain special characters: #, %, ^, &, *",
"maxLength": 80,
"minLength": 1,
"pattern": "^[^#%^&*]+$"
},
"date": {
"type": "string",
"format": "date",
"description": "Date of the holiday in YYYY-MM-DD format. Must be within current or next financial year."
},
"type": {
"type": "string",
"description": "Type of holiday: business_holiday applies to all users, shift_holiday applies to specific shifts",
"enum": [
"business_holiday",
"shift_holiday"
]
},
"shift_hour": {
"type": [
"object",
"null"
],
"description": "Shift hour configuration associated with this holiday (required for shift_holiday type)",
"properties": {
"name": {
"type": "string",
"description": "Name of the shift hour",
"maxLength": 255
},
"id": {
"type": "string",
"description": "Unique identifier of the shift hour",
"pattern": "^[0-9]+$",
"maxLength": 255
}
},
"required": [
"name",
"id"
],
"additionalProperties": false
},
"id": {
"type": "string",
"description": "Unique identifier of the holiday",
"pattern": "^[0-9]+$",
"maxLength": 255
},
"year": {
"type": "integer",
"format": "int32",
"description": "Year of the holiday",
"minimum": 2000,
"maximum": 2100
}
},
"required": [
"name",
"date",
"type",
"shift_hour",
"id",
"year"
],
"description": "The Item of the object.",
"additionalProperties": false
},
"maxItems": 100
},
"info": {
"type": "object",
"description": "Pagination metadata for the response",
"properties": {
"per_page": {
"type": "integer",
"format": "int32",
"description": "Number of records returned per page",
"minimum": 1
},
"page": {
"type": "integer",
"format": "int32",
"description": "Current page number (1-indexed)",
"minimum": 1
},
"count": {
"type": "integer",
"format": "int32",
"description": "Total number of records returned in this response",
"minimum": 0
},
"more_records": {
"type": "boolean",
"description": "Indicates whether more records are available on subsequent pages"
}
},
"additionalProperties": false
}
},
"required": [
"holidays"
],
"description": "The Response body of the object.",
"additionalProperties": false
}
}
}
},
"204": {
"description": "No Content - No holidays found matching the specified filter criteria"
},
"400": {
"description": "Bad request - validation errors",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"PATTERN_NOT_MATCHED"
],
"description": "The Code of the object."
},
"details": {
"type": "object",
"description": "The Details of the object.",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "The Message of the object.",
"maxLength": 255
},
"status": {
"type": "string",
"enum": [
"error"
],
"description": "The Status of the object."
}
},
"description": "The Response body of the object.",
"additionalProperties": false
}
}
}
}
}
},
"post": {
"tags": [
"Holidays"
],
"summary": "Create holidays",
"description": "Creates one or more holidays with specified names, dates, types, and associated shift hours. Each holiday must have a unique name and date combination. Business holidays apply to all users, while shift holidays require a valid shift_hour association.",
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.business_hours.CREATE"
]
}
],
"operationId": "createHolidays",
"requestBody": {
"description": "Request body containing an array of holidays to create. Each holiday must include a name, date, type, and shift_hour association (for shift holidays).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"holidays": {
"type": "array",
"description": "Array of holiday objects to create. Maximum 52 holidays allowed per type per year.",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the holiday. Cannot contain special characters: #, %, ^, &, *",
"maxLength": 80,
"minLength": 1,
"pattern": "^[^#%^&*]+$"
},
"date": {
"type": "string",
"format": "date",
"description": "Date of the holiday in YYYY-MM-DD format. Must be within current or next financial year."
},
"type": {
"type": "string",
"description": "Type of holiday: business_holiday applies to all users, shift_holiday applies to specific shifts",
"enum": [
"business_holiday",
"shift_holiday"
]
},
"shift_hour": {
"type": "object",
"description": "Shift hour association (required when type is shift_holiday, should be null or omitted for business_holiday)",
"properties": {
"name": {
"type": "string",
"description": "Name of the shift hour",
"maxLength": 255
},
"id": {
"type": "string",
"description": "Unique identifier of the shift hour",
"pattern": "^[0-9]+$",
"maxLength": 255
}
},
"required": [
"name",
"id"
],
"additionalProperties": false
}
},
"required": [
"name",
"date",
"type",
"shift_hour"
],
"description": "The Item of the object.",
"additionalProperties": false
},
"maxItems": 100
},
"info": {
"type": "object",
"properties": {
"per_page": {
"type": "integer",
"format": "int32",
"description": "The Per page of the object."
},
"page": {
"type": "integer",
"format": "int32",
"description": "The Page of the object."
},
"count": {
"type": "integer",
"format": "int32",
"description": "The Count of the object."
},
"more_records": {
"type": "boolean",
"description": "The More records of the object."
}
},
"description": "The Info of the object.",
"additionalProperties": false
}
},
"description": "The Request body of the object.",
"additionalProperties": false
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Holidays created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"holidays": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"SUCCESS"
],
"description": "The Code of the object."
},
"details": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the holiday",
"maxLength": 255
}
},
"description": "The Details of the object.",
"additionalProperties": false
},
"message": {
"type": "string",
"description": "The Message of the object.",
"maxLength": 255
},
"status": {
"type": "string",
"enum": [
"success"
],
"description": "The Status of the object."
}
},
"required": [
"code",
"details",
"message",
"status"
],
"description": "The Item of the object.",
"additionalProperties": false
},
"description": "The Holidays of the object.",
"maxItems": 100
}
},
"required": [
"holidays"
],
"description": "The Response body of the object.",
"additionalProperties": false
}
}
}
},
"400": {
"description": "Bad request - validation errors",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"holidays": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"MANDATORY_NOT_FOUND",
"LIMIT_EXCEEDED",
"DUPLICATE_DATA",
"DEPENDENT_FIELD_MISSING",
"INVALID_DATA"
],
"description": "The Code of the object."
},
"details": {
"type": "object",
"description": "The Details of the object.",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "The Message of the object.",
"maxLength": 255
},
"status": {
"type": "string",
"enum": [
"error"
],
"description": "The Status of the object."
}
},
"description": "The Item of the object.",
"additionalProperties": false
},
"description": "The Holidays of the object.",
"maxItems": 100
}
},
"description": "The Response body of the object.",
"additionalProperties": false
}
}
}
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
}
},
"put": {
"tags": [
"Holidays"
],
"summary": "Update holidays (bulk)",
"description": "Updates one or more existing holidays by their IDs with new names, dates, or shift hour associations.",
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.business_hours.UPDATE"
]
}
],
"operationId": "updateHolidays",
"requestBody": {
"description": "Request body containing an array of holidays to update. Each holiday must include its ID along with the fields to update.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"holidays": {
"type": "array",
"description": "Array of holiday objects to update with their IDs and new values",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the holiday. Cannot contain special characters: #, %, ^, &, *",
"maxLength": 80,
"minLength": 1,
"pattern": "^[^#%^&*]+$"
},
"date": {
"type": "string",
"format": "date",
"description": "Date of the holiday in YYYY-MM-DD format. Must be within current or next financial year."
},
"type": {
"type": "string",
"description": "Type of holiday: business_holiday applies to all users, shift_holiday applies to specific shifts",
"enum": [
"business_holiday",
"shift_holiday"
]
},
"shift_hour": {
"type": "object",
"description": "Shift hour association (required when type is shift_holiday)",
"properties": {
"name": {
"type": "string",
"description": "Name of the shift hour",
"maxLength": 255
},
"id": {
"type": "string",
"description": "Unique identifier of the shift hour",
"pattern": "^[0-9]+$",
"maxLength": 255
}
},
"required": [
"name",
"id"
],
"additionalProperties": false
},
"id": {
"type": "string",
"description": "Unique identifier of the holiday to update",
"pattern": "^[0-9]+$",
"maxLength": 255
}
},
"required": [
"name",
"date",
"type",
"shift_hour",
"id"
],
"description": "The Item of the object.",
"additionalProperties": false
},
"maxItems": 100
},
"info": {
"type": "object",
"properties": {
"per_page": {
"type": "integer",
"format": "int32",
"description": "The Per page of the object."
},
"page": {
"type": "integer",
"format": "int32",
"description": "The Page of the object."
},
"count": {
"type": "integer",
"format": "int32",
"description": "The Count of the object."
},
"more_records": {
"type": "boolean",
"description": "The More records of the object."
}
},
"description": "The Info of the object.",
"additionalProperties": false
}
},
"description": "A object value.",
"additionalProperties": false
}
],
"description": "The Request body of the object."
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Success - Holidays updated successfully. Returns array of result objects with status for each holiday.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"holidays": {
"type": "array",
"description": "Array of operation results for each holiday update request",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Result code indicating success or failure",
"maxLength": 255
},
"details": {
"type": "object",
"description": "Additional details about the operation result",
"properties": {
"id": {
"type": "string",
"description": "The ID of the updated holiday",
"maxLength": 255
}
},
"additionalProperties": false
},
"message": {
"type": "string",
"description": "Human-readable message describing the result",
"maxLength": 255
},
"status": {
"type": "string",
"description": "Operation status",
"maxLength": 255
}
},
"description": "The Item of the object.",
"additionalProperties": false
},
"maxItems": 100
}
},
"required": [
"holidays"
],
"description": "The Response body of the object.",
"additionalProperties": false
}
}
}
},
"400": {
"description": "Bad request - validation errors",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"holidays": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"DUPLICATE_DATA",
"DEPENDENT_FIELD_MISSING",
"INVALID_DATA"
],
"description": "The Code of the object."
},
"details": {
"type": "object",
"description": "The Details of the object.",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "The Message of the object.",
"maxLength": 255
},
"status": {
"type": "string",
"enum": [
"error"
],
"description": "The Status of the object."
}
},
"description": "The Item of the object.",
"additionalProperties": false
},
"description": "The Holidays of the object.",
"maxItems": 100
}
},
"description": "The Response body of the object.",
"additionalProperties": false
}
}
}
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
}
}
}
},
"/settings/holidays/{holidayId}": {
"put": {
"tags": [
"Holidays"
],
"summary": "Update a specific holiday",
"description": "Updates a specific holiday identified by its ID. You can modify the holiday's name (max 80 characters, no special characters: #, %, ^, &, *) or date (must be within current or next financial year). Provide only the fields you want to update.",
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.business_hours.UPDATE"
]
}
],
"operationId": "updateHoliday",
"parameters": [
{
"$ref": "#/components/parameters/HolidayId"
}
],
"requestBody": {
"description": "Request body containing the fields to update for the holiday. Provide only the fields you wish to change.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"holidays": {
"type": "array",
"description": "Array containing a single holiday object with fields to update",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "New name for the holiday. Cannot contain special characters: #, %, ^, &, *. Set to null to keep existing value.",
"maxLength": 80,
"minLength": 1,
"pattern": "^[^#%^&*]+$"
},
"date": {
"type": [
"string",
"null"
],
"format": "date",
"description": "New date for the holiday in YYYY-MM-DD format. Must be within current or next financial year. Set to null to keep existing value."
}
},
"description": "The Item of the object.",
"additionalProperties": false
}
}
},
"description": "The Request body of the object.",
"additionalProperties": false
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Holiday updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"holidays": {
"type": "array",
"items": {
"type": "object",
"properties": {
"c
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-holidays-openapi.json