> ## Documentation Index > Fetch the complete documentation index at: https://developer.zeeg.me/llms.txt > Use this file to discover all available pages before exploring further. # Create Holiday Subscriptions > Bulk-subscribe one or more users to a holiday category so the listed dates are automatically blocked from their availability. ## OpenAPI ````yaml POST /holidays/subscriptions openapi: 3.0.0 info: title: Zeeg Public API description: >- Zeeg public API documentation. ## Authentication All endpoints require a Bearer token. You can generate an API token from [your Zeeg dashboard](https://app.zeeg.me/account/settings/api-access). Each token is scoped to specific permissions (e.g. `events:read`, `webhooks:write`). Make sure your token has the required scopes for the endpoints you want to use. ## Recommended Headers We recommend including the `Accept: application/json` header in all API requests to ensure you receive JSON responses. version: 2.0.0 x-logo: url: https://app.zeeg.me/img/logo-dark.2ca83593.svg backgroundColor: '#f7f7f9' altText: zeeg contact: name: Zeeg Support email: support@zeeg.me url: https://zeeg.me/en/contact license: name: Proprietary url: https://zeeg.me/en/legal/terms termsOfService: https://zeeg.me/en/legal/terms servers: - url: https://api.zeeg.me/v2 description: Production security: - bearer: [] tags: - name: Scheduled Events description: Management of events scheduled via Zeeg - name: Scheduling Pages description: Scheduling pages information and management - name: Availability Schedule description: Read and change availability for users - name: Webhooks description: Webhooks management - name: Notes description: Notes for scheduled events - name: Workspaces & Teams description: Workspace users and team member management - name: AI Agent description: AI Agent integration endpoints - name: Payloads description: Webhook payload schemas - name: CRM - Objects description: >- Discover the schema of CRM objects (standard and custom) including all attribute definitions - name: CRM - Companies description: Create, read, update, and delete CRM company records - name: CRM - People description: Create, read, update, and delete CRM person records paths: /holidays/subscriptions: post: tags: - Availability Schedule summary: Create holiday subscriptions description: >- Subscribe one or more users (or every active member of one team) to a holiday category in a single request. Provide **exactly one** of `users` or `team`: - `users`: subscribe each resolved user. Inside `users`, provide exactly one identifier type — `emails`, `slugs`, or `uuids` — with up to 10 entries. - `team`: subscribe every active member of a team. Identify the team by either `team.uuid` (the team's UUID) or `team.slug`. Teams with more than 200 active members cannot be processed in a single request. **Idempotency:** if a target user is already subscribed to the same category, the entry is reported as `skipped` (not an error). When `excludedHolidayKeys` is supplied alongside a skipped entry, the new keys are *added* to that user's overrides without removing pre-existing ones. **Authorization:** the token's owner must be allowed to edit schedules for each resolved user, otherwise that entry is reported as `failed`. The HTTP response is 200 if at least one entry succeeded; 422 when none succeeded. Every result entry always includes the target's `email`, `slug` and `uuid` when the user resolves. For unresolved identifiers, only the field matching the lookup type is populated. operationId: create-holiday-subscriptions requestBody: required: true content: application/json: schema: type: object required: - subscription properties: users: type: object description: >- User-based target. Mutually exclusive with `team`. Provide exactly one of `emails`, `slugs` or `uuids`. properties: emails: type: array minItems: 1 maxItems: 10 items: type: string format: email slugs: type: array minItems: 1 maxItems: 10 items: type: string uuids: type: array minItems: 1 maxItems: 10 items: type: string format: uuid team: type: object description: >- Team-based target. Mutually exclusive with `users`. Provide exactly one of `uuid` or `slug`. properties: uuid: type: string format: uuid slug: type: string subscription: type: object required: - categoryType - categoryKey properties: categoryType: type: string enum: - country - region categoryKey: type: string maxLength: 30 description: >- Country or region key from `/holidays/categories` (e.g. `DE`, `DE-BY`). excludedHolidayKeys: type: array nullable: true description: >- Holiday keys (from `/holidays/preview`) to exclude from each target's availability. items: type: string maxLength: 100 examples: Subscribe self to country: value: users: emails: - lena.meier@horizondigital.de subscription: categoryType: country categoryKey: DE Subscribe users to a region with exclusions: value: users: emails: - lena.meier@horizondigital.de - tom.schmidt@horizondigital.de subscription: categoryType: region categoryKey: DE-BY excludedHolidayKeys: - easter-monday - christmas-day Team by UUID: value: team: uuid: 01907a20-1234-7abc-9def-001122334455 subscription: categoryType: country categoryKey: DE responses: '200': description: At least one target was created or skipped. content: application/json: schema: oneOf: - type: object required: - users properties: users: type: array items: $ref: '#/components/schemas/BulkHolidaySubscriptionResult' - type: object required: - team - members properties: team: type: object properties: uuid: type: string format: uuid slug: type: string name: type: string members: type: array items: $ref: '#/components/schemas/BulkHolidaySubscriptionResult' examples: Users — mixed outcome: value: users: - email: lena.meier@horizondigital.de slug: lena-meier uuid: Lena6mK2QwR9XPv status: created - email: tom.schmidt@horizondigital.de slug: tom-schmidt uuid: TomXk3J8YqB1ZPN status: skipped Team: value: team: uuid: 01907a20-1234-7abc-9def-001122334455 slug: engineering name: Engineering members: - email: lena.meier@horizondigital.de slug: lena-meier uuid: Lena6mK2QwR9XPv status: created - email: bob.keller@horizondigital.de slug: bob-keller uuid: Bob5pH7KvF2WMRa status: failed reason: Not allowed to edit schedules for this user. '401': $ref: '#/components/responses/401' '404': description: Team not found, or holiday category not found. content: application/json: examples: Unknown category: value: success: false status: 404 message: Holiday category not found. Team not found: value: success: false status: 404 message: Team not found. '422': description: Validation error, all targets failed, or team is too large. content: application/json: examples: Target missing: value: message: Provide exactly one of "users" or "team". errors: target: - Provide exactly one of "users" or "team". Team too large: value: success: false status: 422 message: >- Team has more active members than can be processed in a single request. All entries failed: value: users: - email: typo@example.com slug: null uuid: null status: failed reason: User not found. security: - bearer: [] components: schemas: BulkHolidaySubscriptionResult: type: object description: Per-target outcome of a bulk holiday-subscription create call. required: - email - slug - uuid - status properties: email: type: string format: email nullable: true description: >- Target user's email, or the lookup key when resolution failed for an `emails` request. slug: type: string nullable: true description: >- Target user's slug, or the lookup key when resolution failed for a `slugs` request. uuid: type: string format: uuid nullable: true description: >- Target user's public UUID, or the lookup key when resolution failed for a `uuids` request. status: type: string enum: - created - skipped - failed description: >- `created` — new subscription added. `skipped` — user was already subscribed to the same category (any new `excludedHolidayKeys` were merged in). `failed` — see `reason`. reason: type: string description: >- Human-readable failure reason. Present only when `status` is `failed`. responses: '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Unauthenticated. examples: Unauthenticated: value: message: Unauthenticated. securitySchemes: bearer: type: http scheme: bearer description: '' ````