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

# Get calendar by external ID

Get a holiday calendar given its external ID in path.

# 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": {
      "ExternalIdPath": {
        "name": "external_id",
        "in": "path",
        "description": "Client-created calendar holiday ID",
        "required": true,
        "schema": {
          "type": "string",
          "maxLength": 36
        }
      }
    },
    "schemas": {
      "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"
      },
      "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.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"
          }
        }
      }
    },
    "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/external-id/{external_id}": {
      "get": {
        "summary": "Get calendar by external ID",
        "description": "Get a holiday calendar given its external ID in path.",
        "operationId": "get-holiday-calendar-by-external-id",
        "tags": [
          "Holiday calendar data"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ExternalIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/presenter.GetHolidayCalendarResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/500InternalServerError"
          }
        }
      }
    }
  }
}
```