Holidays

Request a Holiday.

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.

<strong>Note:</strong> This will raise a Webhook event if you have Webhooks configured.

<strong>Important:</strong> a booking that is refused still returns <strong>200</strong>. 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.

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

Request body

fromstring date-time

The start date of the request. Don't include any time information.

tostring date-time

The end date of the requeset. Don't include any time information.

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

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

leaveTypeIdinteger

The leave type for the request

reasonstring nullable

An optional reason for the request.

userOrDepartmentIdinteger

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
suppressEmailsboolean

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.

overrideboolean

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.

bookAsRequesteeboolean

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.

overrideLockedDaysboolean

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.

overrideAccruedAllowanceboolean

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.

attachmentIdinteger nullable

If you've added an attachment, assign it to this booking by passing the ID here.

Response

The request was processed. Check success in the body — this is also returned when the booking was refused.

successboolean

Whether the booking request was successfull or not

responsestring nullable

A response message from the booking request

rejectionsboolean

Whether there were any rejections with the booking, if it was against a department

autoApprovedboolean

Whether the request was automatically approved or not

holidayIdinteger

The ID of the newly created holiday

overrideRequiredboolean

Whether the holiday can be force-added (as in bypassing the max off limit)

overrideLockedDateRequiredboolean

Whether the holiday can be force-added (overriding any locked dates)

overrideAccruedAllowanceRequiredboolean

Whether the holiday can be force-added (as in bypassing the accrued allowance)

Changes

No recorded changes to this operation across all 1 revision of this API.