> ## 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 Time-Off Periods > Bulk-create time-off periods for one or more users (by email, slug, or UUID) to block their availability for vacations or absences. ## OpenAPI ````yaml POST /time-off 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: /time-off: post: tags: - Availability Schedule summary: Create time-off periods description: >- Create one or more time-off periods in a single request. Provide **exactly one** of `users` or `team`: - `users`: create the same period for each resolved user. Inside `users`, provide exactly one identifier type — `emails`, `slugs`, or `uuids` — with up to 10 entries. - `team`: create the same period for 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. **Overlap semantics:** any existing period for a target user that overlaps the new date range is deleted and returned in the `replaced` array for that user; the entry's `status` becomes `replaced` instead of `created`. **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 period was created or replaced; 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: post-time-off requestBody: required: true content: application/json: schema: type: object required: - type - title - startDate - endDate 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 type: type: string enum: - vacation - out_of_office title: type: string maxLength: 255 startDate: type: string format: date endDate: type: string format: date startHalfDay: type: boolean endHalfDay: type: boolean startHalfDayCutoff: type: string nullable: true description: >- Half-day cutoff (HH:MM). Required when `startHalfDay` is true. endHalfDayCutoff: type: string nullable: true description: Half-day cutoff (HH:MM). Required when `endHalfDay` is true. note: type: string nullable: true maxLength: 1000 examples: Users by email: value: users: emails: - lena.meier@horizondigital.de - tom.schmidt@horizondigital.de type: vacation title: Company offsite startDate: '2026-09-01' endDate: '2026-09-04' Team by UUID: value: team: uuid: 01907a20-1234-7abc-9def-001122334455 type: out_of_office title: Team strategy days startDate: '2026-10-12' endDate: '2026-10-13' responses: '200': description: At least one period was created or replaced. content: application/json: schema: oneOf: - type: object required: - users properties: users: type: array items: $ref: '#/components/schemas/BulkTimeOffResult' - 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/BulkTimeOffResult' examples: Users — mixed outcome: value: users: - email: lena.meier@horizondigital.de slug: lena-meier uuid: Lena6mK2QwR9XPv status: created period: uuid: 01907f10-5b00-7b31-9cf0-1234567890ab uri: >- https://api.zeeg.me/v2/time-off/01907f10-5b00-7b31-9cf0-1234567890ab type: vacation title: Company offsite startDate: '2026-09-01' endDate: '2026-09-04' startHalfDay: false endHalfDay: false startHalfDayCutoff: null endHalfDayCutoff: null note: null replaced: [] - email: tom.schmidt@horizondigital.de slug: tom-schmidt uuid: TomXk3J8YqB1ZPN status: replaced period: uuid: 01907f10-5b00-7b31-9cf0-2222333344ff uri: >- https://api.zeeg.me/v2/time-off/01907f10-5b00-7b31-9cf0-2222333344ff type: vacation title: Company offsite startDate: '2026-09-01' endDate: '2026-09-04' startHalfDay: false endHalfDay: false startHalfDayCutoff: null endHalfDayCutoff: null note: null replaced: - 01907f10-5b00-7b31-9cf0-9999888877aa 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 period: uuid: 01907f10-5b00-7b31-9cf0-1234567890ab uri: >- https://api.zeeg.me/v2/time-off/01907f10-5b00-7b31-9cf0-1234567890ab type: out_of_office title: Team strategy days startDate: '2026-10-12' endDate: '2026-10-13' startHalfDay: false endHalfDay: false startHalfDayCutoff: null endHalfDayCutoff: null note: null replaced: [] - 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. content: application/json: examples: 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: BulkTimeOffResult: type: object description: Per-target outcome of a bulk time-off 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 - replaced - failed period: description: >- The created time-off period. Present when `status` is `created` or `replaced`. type: object properties: uuid: type: string format: uuid uri: type: string format: uri type: type: string enum: - vacation - out_of_office title: type: string nullable: true startDate: type: string format: date endDate: type: string format: date startHalfDay: type: boolean endHalfDay: type: boolean startHalfDayCutoff: type: string nullable: true endHalfDayCutoff: type: string nullable: true note: type: string nullable: true replaced: type: array description: >- UUIDs of pre-existing periods deleted due to overlap. Empty on `created`, non-empty on `replaced`, absent on `failed`. items: type: string format: uuid 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: '' ````