---
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.

# List holiday calendars

List holiday calendars for an Organization.

# 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 data"
    }
  ],
  "components": {
    "parameters": {
      "CIDheader": {
        "name": "x-cid",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "description": "The Correlation IDentifier UUID field links related API requests and events. The `x-cid` can help the Pismo engineering team track everything related to a call. If not passed, this field is automatically generated.\n"
      },
      "ExternalIdQuery": {
        "name": "external_id",
        "in": "query",
        "description": "Client-created calendar holiday ID",
        "schema": {
          "type": "string",
          "maxLength": 36
        }
      },
      "HolidayCalendarNameQuery": {
        "name": "name",
        "in": "query",
        "description": "Holiday calendar name filter",
        "schema": {
          "type": "string",
          "maxLength": 80,
          "example": "Independance Day"
        }
      },
      "HolidayCalendarTypeQuery": {
        "name": "type",
        "in": "query",
        "description": "Holiday calendar type filter",
        "schema": {
          "type": "string"
        }
      },
      "HolidayCalendarIdQuery": {
        "name": "holiday_calendar_id",
        "in": "query",
        "description": "Holiday calendar ID filter",
        "required": false,
        "schema": {
          "type": "integer"
        }
      },
      "HolidayCalendarParentIdQuery": {
        "name": "parent_id",
        "in": "query",
        "description": "Holiday calendar parent ID filter",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "format": "int32",
          "example": 5
        }
      },
      "HolidayCalendarSortByQuery": {
        "name": "sort_by",
        "in": "query",
        "description": "Sort field - `name` or `type`. Default is `name`.",
        "schema": {
          "type": "string",
          "enum": [
            "name",
            "type"
          ],
          "example": "name",
          "default": "name"
        }
      },
      "HolidayCalendarSortOrderQuery": {
        "name": "sort_order",
        "in": "query",
        "description": "Sort order - `asc` or `desc`. Default is `asc`",
        "schema": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ],
          "default": "asc"
        }
      },
      "OrgHeader": {
        "name": "x-tenant",
        "in": "header",
        "description": "Organization/tenant ID",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "PageNumberQuery": {
        "name": "page",
        "in": "query",
        "description": "Page number.  Default = `1`.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "format": "int32",
          "example": 5
        }
      },
      "PerPageQuery": {
        "name": "perPage",
        "in": "query",
        "description": "Items per page. Default =  `10`. Maximum = `100`.",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 100,
          "example": 30
        }
      },
      "relationQuery": {
        "name": "relation",
        "in": "query",
        "description": "Calendar relationship type. Default is all Organization calendars. Either `external_id` or `holiday_calendar_id` is **REQUIRED** if this field is passed.",
        "schema": {
          "type": "string",
          "enum": [
            "parents",
            "children"
          ]
        }
      }
    },
    "schemas": {
      "CurrentPage": {
        "type": "integer",
        "description": "Current result page",
        "example": 1
      },
      "ExternalId": {
        "type": "string",
        "description": "Client-created external ID",
        "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"
      },
      "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"
      },
      "Pages": {
        "type": "integer",
        "description": "Total number of result pages.",
        "example": 1
      },
      "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
      },
      "PerPage": {
        "type": "integer",
        "description": "Maximum results per page",
        "example": 10
      },
      "presenter.GetHolidayCalendarResponse": {
        "type": "object",
        "properties": {
          "external_id": {
            "$ref": "#/components/schemas/ExternalId"
          },
          "holiday_calendar_id": {
            "$ref": "#/components/schemas/HolidayCalendarID"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          },
          "name": {
            "$ref": "#/components/schemas/HolidayCalendarName"
          },
          "parent_id": {
            "$ref": "#/components/schemas/ParentId"
          },
          "type": {
            "$ref": "#/components/schemas/HolidayType"
          },
          "working_days": {
            "$ref": "#/components/schemas/HolidayWorkingDays"
          }
        }
      },
      "presenter.ListHolidayCalendarResponse": {
        "type": "object",
        "properties": {
          "current_page": {
            "$ref": "#/components/schemas/CurrentPage"
          },
          "pages": {
            "$ref": "#/components/schemas/Pages"
          },
          "per_page": {
            "$ref": "#/components/schemas/PerPage"
          },
          "total_items": {
            "$ref": "#/components/schemas/TotalItems"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/presenter.GetHolidayCalendarResponse"
            }
          }
        }
      },
      "TotalItems": {
        "type": "integer",
        "description": "Total number of result items",
        "example": 11
      }
    },
    "responses": {
      "400BadRequest": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/handler.HTTPError"
            },
            "examples": {
              "missing-x-tenant-header": {
                "$ref": "#/components/examples/BadRequestResponseMissingHeader"
              },
              "invalid-id-params": {
                "$ref": "#/components/examples/BadRequestResponseInvalidParams"
              }
            }
          }
        }
      },
      "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"
        }
      },
      "BadRequestResponseInvalidParams": {
        "value": {
          "code": "400",
          "message": "Invalid parameter value: {parameter name}"
        }
      }
    }
  },
  "paths": {
    "/v1/holiday-calendar": {
      "get": {
        "summary": "List holiday calendars",
        "description": "List holiday calendars for an Organization.",
        "operationId": "list-holiday-calendars",
        "tags": [
          "Holiday calendar data"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/OrgHeader"
          },
          {
            "$ref": "#/components/parameters/CIDheader"
          },
          {
            "$ref": "#/components/parameters/HolidayCalendarIdQuery"
          },
          {
            "$ref": "#/components/parameters/HolidayCalendarNameQuery"
          },
          {
            "$ref": "#/components/parameters/HolidayCalendarTypeQuery"
          },
          {
            "$ref": "#/components/parameters/ExternalIdQuery"
          },
          {
            "$ref": "#/components/parameters/HolidayCalendarParentIdQuery"
          },
          {
            "$ref": "#/components/parameters/HolidayCalendarSortByQuery"
          },
          {
            "$ref": "#/components/parameters/HolidayCalendarSortOrderQuery"
          },
          {
            "$ref": "#/components/parameters/relationQuery"
          },
          {
            "$ref": "#/components/parameters/PageNumberQuery"
          },
          {
            "$ref": "#/components/parameters/PerPageQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/presenter.ListHolidayCalendarResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/500InternalServerError"
          }
        }
      }
    }
  }
}
```