--- title: "Request a Holiday." method: POST path: "/api/holidays" tags: ["Holidays"] --- # Request a Holiday. `POST /api/holidays` ## Request - Base URL: `https://app.timetastic.co.uk` (the document declares no server; this is the origin it was published from) - URL: `https://app.timetastic.co.uk/api/holidays` - Auth: none declared Use this to submit a leave request to Timetastic. Depending on your authorisation, you can book for yourself, any other user at your organisation, your department, or the entire organisation. Note: This will raise a Webhook event if you have Webhooks configured. Important: a booking that is refused still returns 200. Always check `success` in the response body rather than relying on the status code. When `success` is `false`, `response` explains why. Reasons include: the dates contain no working days for that user, the request is zero length, the end date is before the start date, the user is already off for some of those dates, the user has insufficient allowance (or insufficient accrued allowance), the leave type is not active or its limit has been exceeded, the dates fall before the user's start date or after their end date, the dates are too far in the future, the leave year's allowance has not been created yet, a maximum-off limit would be breached, or the dates are locked. Three of those refusals can be retried with an override, and are flagged separately so you can prompt for confirmation. Resubmit with the matching request field set to book anyway — each one requires the appropriate permission: - `overrideRequired` (a maximum-off limit) → resubmit with `override` - `overrideLockedDateRequired` (a locked date) → resubmit with `overrideLockedDays` - `overrideAccruedAllowanceRequired` (accrued allowance) → resubmit with `overrideAccruedAllowance` When booking for a department or the whole organisation, `rejections` indicates that some users in the group could not be booked; `response` summarises which. ## Request body - TimetasticCoreModelsApiModelsBookHolidayModel: Represent a leave booking request - `from` string, date-time: The start date of the request. Don't include any time information. - `to` string, date-time: The end date of the requeset. Don't include any time information. - `fromTime` string, nullable: Use in conjuction with the From to denote the part of day that the leave request starts. AM: Starts in the morning of the day. PM: Starts at lunchtime of the day. Number: Alternatively, for hourly bookings, you can specify a time, expressed as minutes since midnight. - `toTime` string, nullable: Use in conjuction with the To to denote the part of day that the leave request ends. AM: Ends at the end of the the morning (lunchtime). PM: Ends at the end of the day. Number: Alternatively, for hourly bookings, you can specify a time, expressed as minutes since midnight. - `leaveTypeId` integer: The leave type for the request - `reason` string, nullable: An optional reason for the request. - `userOrDepartmentId` integer: The ID of the user or department you are making the request for. Use in conjunction with BookFor. - `bookFor` 'User' | 'Department' | 'Everyone': Flag to set if you are booking for a user, department, or everyone. - `User` - `Department` - `Everyone` - `suppressEmails` boolean: If you are an admin, you can request that emails are suppressed for this request. This will prevent any leave request emails from being sent when the request is processed. - `override` boolean: If you are an admin, and the booking would be rejected because it exceeds the max-off limit for this department, setting override allows you to make the booking despite that limit. - `bookAsRequestee` boolean: If you are an admin, set this to true to make the leave request as though it were being made by the requestee (the person you are booking for). This ensures the normal approval flow will happen. The default is false - leave requests will be booked by the admin user account making the API call. - `overrideLockedDays` boolean: If you are an admin, and the booking would be rejected because it covers locked dates setting OverrideLockedDays allows you to make the booking ignoring existing locks. - `overrideAccruedAllowance` boolean: If you are an admin, and the booking would be rejected because it doesn't have enough accrued allowance, but has enough annual allowance. setting OverrideAccruedAllowance allows you to make the booking ignoring accrued allowance. - `attachmentId` integer, nullable: If you've added an attachment, assign it to this booking by passing the ID here. ## Response `200` The request was processed. Check `success` in the body — this is also returned when the booking was refused. - TimetasticWebApiResourceModelsHolidayBookResult: Contains the results of a holiday book operation - `success` boolean: Whether the booking request was successfull or not - `response` string, nullable: A response message from the booking request - `rejections` boolean: Whether there were any rejections with the booking, if it was against a department - `autoApproved` boolean: Whether the request was automatically approved or not - `holidayId` integer: The ID of the newly created holiday - `overrideRequired` boolean: Whether the holiday can be force-added (as in bypassing the max off limit) - `overrideLockedDateRequired` boolean: Whether the holiday can be force-added (overriding any locked dates) - `overrideAccruedAllowanceRequired` boolean: Whether the holiday can be force-added (as in bypassing the accrued allowance) ## Other responses - `400`: The request itself was malformed. The body is a plain string. Returned when the request could not be read, and when a non-administrator tried to book for everyone. - `401`: The request was not authenticated — the API token is missing or invalid. - `429`: The overall API rate limit was exceeded. --- [API](https://skmtc.dev/timetastic/apis/timetastic-api.md) · [All operations](https://skmtc.dev/timetastic/apis/timetastic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/timetastic/apis/timetastic-api/revisions/709ccb0412c3?raw)