Bookings

The Booking object represents a scheduled time allocation for a person, serving as a core component for tracking time, managing availability, and organizing resource allocation. There are two main types of bookings:

  1. Budget bookings - where a person is allocated to work on a specific deal/budget. These bookings are linked to a service object, which represents the actual work being done.

  2. Absence bookings - which track time off and remote work absences. These bookings are linked to an event object, representing the type of absence (time off or remote work).

Each booking method defines how time is allocated and requires specific attributes to be set: Per day (requires hours and time attributes to specify hours and time for each day), Percentage (requires percentage attribute to allocate a portion of a person's available time) and Total hours (requires total_time attribute to specify the total amount of hours for the selected period).

Bookings can have different states depending on their type:

  • Budget bookings can be either Tentative (when there's a possibility of the time allocation but it's not yet confirmed, indicated by draft: true) or Confirmed
  • Absence bookings go through an approval workflow with the following states: Pending (waiting for approval), Approved, Rejected (with a reason), or Canceled (if cancelled after submitting for approval)

Bookings can also be customized with custom fields to store additional information about booking. Custom fields allow you to add custom attributes or any other metadata relevant to your booking workflow. For more details on how to work with custom fields please refer to Working with custom fields guide.

The following diagram shows bookings in our data hierarchy:

PersonServiceEventBooking

Attributes

after string
Parameter `filter`

Internal field used for date-range filtering.
approval_status integer
Parameter `filter` Enum

Whether the booking has been approved. Reflects the overall approval_status.

Enum Values (4 values)

  • 1
  • 2
  • 3
  • 5
approval_statuses array of approval status
Response

Per-approver approval status records for this booking.
approved object
Response

Indicates whether the booking has been approved.
approved_at string
Response Parameter `filter`

Timestamp when the booking was approved, or null if not yet approved.
approver person
Response

The person who approved this booking.
approver_id integer
Request Parameter `filter`

The ID of the person who approved this booking.
attachment_ids object
Request

Array of IDs of files attached to this booking.
attachments array of attachment
Response

Files attached to this booking.
autotracking boolean
Response Request Parameter `filter`

When true, time entries are automatically tracked against this booking.
before string
Parameter `filter`

Internal field used for date-range filtering.
billing_type_id integer
Parameter `filter` Enum

ID of the billing type of the associated service.

Enum Values (4 values)

  • 1
  • 2
  • 3
  • 4
booking_method_id integer
Response Request Enum

ID of the booking method used to create this booking (e.g. hours per day, percentage, total hours).

Enum Values (3 values)

  • 1
    Hours per day
  • 2
    Percentage
  • 3
    Total hours
booking_type string
Parameter `filter`

Whether this is a project booking or an absence booking.
budget_id integer
Parameter `filter`

ID of the budget (deal) associated with the booking's service.
canceled boolean
Response Parameter `filter`

Whether this booking has been canceled.
canceled_at string
Response Parameter `filter`

Date when the booking was canceled.
canceler person
Response

The person who canceled this booking.
company_id integer
Parameter `filter`

ID of the client company associated with this booking.
created_at string
Response Parameter `filter`

Date when the booking was created.
creator person
Response

The person who created this booking.
custom_field_attachments array of attachment
Response

File attachments linked via custom fields on this booking.
custom_field_people array of person
Response

People linked via custom fields on this booking.
custom_fields object
Response Request Parameter `filter`

Custom field values for this booking.
draft boolean
Response Request Parameter `filter` Parameter `sort`

Whether the booking is tentative (draft) or confirmed.
ended_on string
Response Request Parameter `filter`

Booking end date.
event event
Response

The absence event category (e.g. vacation, sick leave) for absence bookings.
event_id integer
Request Parameter `filter`

ID of the absence event category for this booking.
external_id string
Response

External identifier for integration with third-party systems.
hours integer
Response

Scheduled hours per day for this booking.
id integer
Parameter `filter`

Unique identifier of the booking.
last_activity_at string
Response Parameter `filter` Parameter `sort`

Timestamp of the last activity recorded on this booking.
note string
Response Request Parameter `filter`

An optional note or description for this booking.
organization organization
Response

The organization this booking belongs to.
origin booking
Response

The booking origin (e.g. the resource request that generated this booking).
origin_id integer
Request Parameter `filter`

The ID of the origin record (e.g. resource request) that created this booking.
people_custom_fields string
Response Parameter `filter`

Custom field values defined on the assigned person.
percentage integer
Response Request

Scheduled time as a percentage of the person's daily capacity.
person person
Response

The person assigned to this booking.
person_id integer
Request Parameter `filter`

ID of the person assigned to this booking.
person_subsidiary_id integer
Parameter `filter`

ID of the subsidiary the assigned person belongs to.
person_type integer
Parameter `filter` Enum

Type of the assigned person (e.g. employee, contractor, placeholder).

Enum Values (4 values)

  • 1
  • 2
  • 3
  • 4
project_id integer
Parameter `filter`

ID of the project this booking relates to.
project_type integer
Parameter `filter` Enum

Type of the associated project (e.g. billable or internal).

Enum Values (2 values)

  • 1
  • 2
rejected object
Response

Whether this booking has been rejected.
rejected_at string
Response Parameter `filter`

Date when the booking was rejected.
rejected_reason string
Response Request

Reason provided when the booking was rejected.
rejecter person
Response

The person who rejected this booking.
resource_request resource request
Response

The resource request this booking fulfills, if applicable.
resource_request_id integer
Request Parameter `filter`

ID of the resource request this booking fulfills.
scenario_item scenario item
Response

The scenario item this booking is linked to, if created from a scenario.
service service
Response

The budget service being scheduled in this booking.
service_id integer
Request

The ID of the service this booking is scheduled against.
stage_type integer
Response Parameter `filter` Enum

The stage type of the booking within the resource planning workflow.

Enum Values (2 values)

  • 1
  • 2
started_on string
Response Request Parameter `filter` Parameter `sort`

The start date of the booking.
status object
Parameter `filter`

The current approval status of the booking (e.g. pending, approved, rejected).
tags integer
Parameter `filter`

Tags associated with this booking.
task task
Response

The task associated with this booking, if applicable.
task_id integer
Request Parameter `filter`

The ID of the task associated with this booking, if applicable.
time integer
Response Request

The booked time in minutes per day.
total_time integer
Response Request

The total booked time in minutes across the entire booking period.
total_working_days integer
Response

The total number of working days covered by this booking.
updated_at string
Response Parameter `filter`

Timestamp when this booking was last updated.
updater person
Response

The person who last updated this booking.
use_salary_currency boolean
Request

When true, cost calculations use the person's salary currency instead of the service currency.
with_draft boolean
Parameter `filter`

When true, draft bookings are included in availability and planning views.

Operations

GET /api/v2/bookings
Get bookings
POST /api/v2/bookings
Create a booking
DELETE /api/v2/bookings/{id}
Deletes a booking
GET /api/v2/bookings/{id}
Gets a booking
PATCH /api/v2/bookings/{id}
Update a booking
PATCH /api/v2/bookings/{id}/unapprove
Unapproves a booking