--- 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. # Create holiday calendar Creates a new holiday calendar with associated holidays. This endpoint does not generate an event. # 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": { "ExternalId": { "type": "string", "description": "Client-created external ID", "maxLength": 36, "minLength": 1, "example": "f89urqljnahosluiefku" }, "ExternalIdParent": { "type": "string", "description": "Client-created external ID for parent calendar. \nRefer to `parent_id` parameter for more information.\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 }, "HolidayCalendarName": { "type": "string", "description": "Holiday calendar name. Must be unique per organization.", "maxLength": 80, "minLength": 1, "example": "Brazil holiday calendar" }, "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 }, "HolidayType": { "type": "string", "description": "Type, free-form field. For example, `Country` or `Region`.", "maxLength": 15, "minLength": 1, "example": "Country" }, "HolidayWorkingDays": { "type": "array", "description": "Working days array\n\n`1` = Monday, `6` = Saturday. Default = `[1, 2, 3, 4, 5]`.\n", "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "example": [ 1, 2, 3, 4, 5, 6 ] }, "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" }, "ParentId": { "type": "integer", "description": "Calendar parent ID.\n\nHoliday calendars can have parent-child relationships, creating a hierarchy. Child calendars inherit holidays from their parent calendars.\n\nCommon use case: Country → State → City hierarchy\n\nExample:\n - Brazil (parent)\n - São Paulo (child of Brazil)\n - Campinas (child of São Paulo)\n\nWhen you query holidays for Campinas, you automatically get:\n - Campinas city holidays\n - São Paulo state holidays\n - Brazil national holidays\n\nYou can reference the parent calendar using either:\n - `parent_id`: The internal parent calendar ID\n - `parent_external_id`: The parent calendar `external_id`\n", "minimum": 1, "example": 8675309 }, "presenter.CreateHolidayCalendarRequest": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "$ref": "#/components/schemas/HolidayCalendarName" }, "type": { "$ref": "#/components/schemas/HolidayType" }, "external_id": { "$ref": "#/components/schemas/ExternalId" }, "holidays": { "type": "array", "description": "Holidays array", "items": { "$ref": "#/components/schemas/presenter.CreateNewHolidayRequest2" } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "parent_external_id": { "$ref": "#/components/schemas/ExternalIdParent" }, "parent_id": { "$ref": "#/components/schemas/ParentId" }, "working_days": { "$ref": "#/components/schemas/HolidayWorkingDays" } } }, "presenter.CreateHolidayCalendarResponse": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/ExternalId" }, "holiday_calendar_id": { "$ref": "#/components/schemas/HolidayCalendarID" }, "holidays": { "type": "array", "items": { "$ref": "#/components/schemas/presenter.CreateNewHolidayResponse" } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "name": { "$ref": "#/components/schemas/HolidayName" }, "parent_external_id": { "$ref": "#/components/schemas/ExternalIdParent" }, "parent_id": { "$ref": "#/components/schemas/ParentId" }, "type": { "$ref": "#/components/schemas/HolidayType" }, "working_days": { "$ref": "#/components/schemas/HolidayWorkingDays" } } }, "presenter.CreateNewHolidayResponse": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/HolidayDescription" }, "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" } } }, "presenter.CreateNewHolidayRequest2": { "type": "object", "required": [ "name", "holiday_date" ], "properties": { "name": { "$ref": "#/components/schemas/HolidayName" }, "holiday_date": { "$ref": "#/components/schemas/HolidayDate" }, "description": { "$ref": "#/components/schemas/HolidayDescription" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "WorkingDate": { "type": "string", "format": "date", "description": "Next work day following the holiday. Format = yyyy-mm-dd.", "example": "2023-01-02" } }, "responses": { "400BadRequestCreateHolidayCalendar": { "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/BadRequestResponseWorkingDateWrongFormat" }, "invalid-metadata": { "$ref": "#/components/examples/BadRequestResponseInvalidMetadata" } } } } }, "404NotFoundCreateHolidayCalendar": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.HTTPError" }, "examples": { "holiday-calendar-not-found": { "$ref": "#/components/examples/BadRequestResponseHolidayCalendarNotFound" } } } } }, "409ConflicCreateHolidayCalendar": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/handler.HTTPError" }, "examples": { "holiday-calendar-already-exists": { "$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" } }, "BadRequestResponseAlreadyExists": { "value": { "code": "EHLD0027", "message": "Holiday calendar already exists" } }, "BadRequestResponseHolidayWrongFormat": { "value": { "code": "EHLD0028", "message": "Holiday date with the wrong format" } }, "BadRequestResponseWorkingDateWrongFormat": { "value": { "code": "EHLD0030", "message": "Working date with the wrong format" } }, "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": { "post": { "summary": "Create holiday calendar", "description": "Creates a new holiday calendar with associated holidays. \n\nThis endpoint does not generate an event.\n", "operationId": "post-create-holiday-calendar", "tags": [ "Holiday calendar" ], "requestBody": { "description": "Create holiday calendar request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presenter.CreateHolidayCalendarRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presenter.CreateHolidayCalendarResponse" } } } }, "400": { "$ref": "#/components/responses/400BadRequestCreateHolidayCalendar" }, "404": { "$ref": "#/components/responses/404NotFoundCreateHolidayCalendar" }, "409": { "$ref": "#/components/responses/409ConflicCreateHolidayCalendar" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } } } } ```