---
updatedAt: 2026-04-23T11:54:50.000Z
---

Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further.

# Add holiday

Add a new holiday to an existing holiday calendar. 


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Platform setup - Holidays",
    "description": "Manage business and non-business days by organization",
    "version": "v1.0",
    "contact": {
      "name": "Pismo Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/holidays-core",
      "description": "API sandbox server for testing"
    }
  ],
  "security": [
    {
      "S2SAuthentication": []
    }
  ],
  "tags": [
    {
      "name": "Holiday calendar"
    }
  ],
  "components": {
    "schemas": {
      "CreatedAt": {
        "type": "string",
        "format": "datetime",
        "description": "Date and time the holiday was created. Format = yyyy-mm-ddTHH:mm:ss.",
        "example": "2024-04-30T17:24:03"
      },
      "ExternalId": {
        "type": "string",
        "description": "Client-created external ID",
        "maxLength": 36,
        "minLength": 1,
        "example": "f89urqljnahosluiefku"
      },
      "ExternalId2": {
        "type": "string",
        "description": "Client-created external ID. \n\nEither this field or `holiday_calendar_id` is **REQUIRED**. Pass one or the other but not both.\n",
        "maxLength": 36,
        "minLength": 1,
        "example": "f89urqljnahosluiefku"
      },
      "handler.HTTPError": {
        "description": "Error",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code"
          },
          "message": {
            "type": "string",
            "description": "Error message"
          }
        }
      },
      "HolidayCalendarID": {
        "type": "integer",
        "description": "Holiday calendar ID",
        "example": 8675309
      },
      "HolidayCalendarID2": {
        "type": "integer",
        "description": "Holiday calendar ID. \n\nEither this field or `external_id` is **REQUIRED**. Pass one or the other but not both.\n",
        "example": 8675309
      },
      "HolidayDate": {
        "type": "string",
        "description": "Holiday date. Format = yyyy-mm-dd.",
        "example": "2023-12-01"
      },
      "HolidayDescription": {
        "type": "string",
        "description": "Holiday description",
        "maxLength": 500,
        "example": "Day to party like it's 1999"
      },
      "HolidayID": {
        "type": "integer",
        "description": "Holiday ID",
        "example": 8675309
      },
      "HolidayName": {
        "type": "string",
        "description": "Holiday name",
        "example": "New Year's Day",
        "maxLength": 80,
        "minLength": 1
      },
      "Metadata": {
        "type": "object",
        "description": "A valid JSON schema as specified in https://json-schema.org/specification.html. Used to register rules used to authorize the transaction.\n\n**Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis#metadata).\n"
      },
      "presenter.AddHolidayToCalendarRequest": {
        "type": "object",
        "required": [
          "holiday_date",
          "name"
        ],
        "properties": {
          "holiday_date": {
            "$ref": "#/components/schemas/HolidayDate"
          },
          "name": {
            "$ref": "#/components/schemas/HolidayName"
          },
          "description": {
            "$ref": "#/components/schemas/HolidayDescription"
          },
          "external_id": {
            "$ref": "#/components/schemas/ExternalId2"
          },
          "holiday_calendar_id": {
            "$ref": "#/components/schemas/HolidayCalendarID2"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        }
      },
      "presenter.AddHolidayToCalendarResponse": {
        "type": "object",
        "properties": {
          "created_at": {
            "$ref": "#/components/schemas/CreatedAt"
          },
          "description": {
            "$ref": "#/components/schemas/HolidayDescription"
          },
          "external_id": {
            "$ref": "#/components/schemas/ExternalId"
          },
          "holiday_calendar_id": {
            "$ref": "#/components/schemas/HolidayCalendarID"
          },
          "holiday_date": {
            "$ref": "#/components/schemas/HolidayDate"
          },
          "holiday_id": {
            "$ref": "#/components/schemas/HolidayID"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          },
          "name": {
            "$ref": "#/components/schemas/HolidayName"
          },
          "working_date": {
            "$ref": "#/components/schemas/WorkingDate"
          }
        }
      },
      "WorkingDate": {
        "type": "string",
        "format": "date",
        "description": "Next work day following the holiday. Format = yyyy-mm-dd.",
        "example": "2023-01-02"
      }
    },
    "responses": {
      "400BadRequestAddHoliday": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/handler.HTTPError"
            },
            "examples": {
              "missing-x-tenant-header": {
                "$ref": "#/components/examples/BadRequestResponseMissingHeader"
              },
              "missing-required-fields": {
                "$ref": "#/components/examples/BadRequestResponseMissingRequiredFields"
              },
              "holiday-date-wrong-format": {
                "$ref": "#/components/examples/BadRequestResponseHolidayWrongFormat"
              },
              "working-date-wrong-format": {
                "$ref": "#/components/examples/BadRequestResponseHolidayWrongFormat"
              },
              "working-date-before-holiday-date": {
                "$ref": "#/components/examples/BadRequestResponseWorkingDateBeforeHolidayDate"
              },
              "invalid-metadata": {
                "$ref": "#/components/examples/BadRequestResponseInvalidMetadata"
              }
            }
          }
        }
      },
      "404NotFoundAddHoliday": {
        "description": "Not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/handler.HTTPError"
            },
            "examples": {
              "holiday-calendar-not-found": {
                "$ref": "#/components/examples/BadRequestResponseHolidayCalendarNotFound"
              },
              "administrative-division-not-found": {
                "$ref": "#/components/examples/BadRequestResponseAdminDivisionNotFound"
              }
            }
          }
        }
      },
      "409ConflictAddHoliday": {
        "description": "Conflict",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/handler.HTTPError"
            },
            "examples": {
              "holiday-exists-in-group": {
                "$ref": "#/components/examples/BadRequestResponseAlreadyExists"
              }
            }
          }
        }
      },
      "500InternalServerError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/handler.HTTPError"
            },
            "examples": {
              "generic-internal-error": {
                "$ref": "#/components/examples/InternalServerErrorResponse"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "S2SAuthentication": {
        "type": "http",
        "scheme": "bearer",
        "description": "All requests must pass an [account-specific token](https://developers.pismo.io/pismo-docs/docs/account-specific-access-tokens).\n"
      }
    },
    "examples": {
      "InternalServerErrorResponse": {
        "value": {
          "code": "EHLD0001",
          "message": "Something went wrong - please try again"
        }
      },
      "BadRequestResponseMissingHeader": {
        "value": {
          "code": "EHLD0016",
          "message": "Missing x-tenant header"
        }
      },
      "BadRequestResponseAdminDivisionNotFound": {
        "value": {
          "code": "EHLD0026",
          "message": "Administrative division not found"
        }
      },
      "BadRequestResponseAlreadyExists": {
        "value": {
          "code": "EHLD0027",
          "message": "Holiday calendar already exists"
        }
      },
      "BadRequestResponseHolidayWrongFormat": {
        "value": {
          "code": "EHLD0028",
          "message": "Holiday date with the wrong format"
        }
      },
      "BadRequestResponseWorkingDateBeforeHolidayDate": {
        "value": {
          "code": "EHLD0032",
          "message": "Working date before holiday date"
        }
      },
      "BadRequestResponseInvalidMetadata": {
        "value": {
          "code": "EHLD0049",
          "message": "Invalid metadata"
        }
      },
      "BadRequestResponseMissingRequiredFields": {
        "value": {
          "code": "EHLD0050",
          "message": "Missing required fields"
        }
      },
      "BadRequestResponseHolidayCalendarNotFound": {
        "value": {
          "code": "EHLD0052",
          "message": "Holiday calendar not found"
        }
      }
    }
  },
  "paths": {
    "/v1/holiday-calendar/holiday": {
      "post": {
        "summary": "Add holiday",
        "description": "Add a new holiday to an existing holiday calendar. \n",
        "operationId": "post-add-holiday-to-calendar",
        "tags": [
          "Holiday calendar"
        ],
        "requestBody": {
          "description": "Holiday creation request data",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/presenter.AddHolidayToCalendarRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/presenter.AddHolidayToCalendarResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400BadRequestAddHoliday"
          },
          "404": {
            "$ref": "#/components/responses/404NotFoundAddHoliday"
          },
          "409": {
            "$ref": "#/components/responses/409ConflictAddHoliday"
          },
          "500": {
            "$ref": "#/components/responses/500InternalServerError"
          }
        }
      }
    }
  }
}
```