Reservations API

List reservations

List all reservations for an account:

GET /reservations

Response

Status: 200 OK
[
  {
    "id": 5,
    "sourceID": null,
    "name": "Conference Room Reservation",
    "status": "canceled",
    "person_id": 92,
    "start_at": "2020-07-13T14:15:00Z",
    "end_at": "2020-07-13T15:15:00Z",
    "created_at": "2020-07-10T20:28:00-05:00",
    "updated_at": "2020-07-10T20:29:35-05:00",
    "nodeID": "..."
  },
  {
    "id": 6,
    "sourceID": null,
    "name": "Reserve a pool car",
    "status": "being_prepared",
    "person_id": 92,
    "start_at": "2020-07-13T15:00:00Z",
    "end_at": "2020-07-13T23:00:00Z",
    "created_at": "2020-07-11T18:32:42-05:00",
    "updated_at": "2020-07-13T09:30:59-05:00",
    "nodeID": "..."
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of reservations.

Predefined Filters

The following predefined filters are available:

Collection Fields

By default the following fields will appear in collections of reservations:

id sourceID name status person start_at end_at created_at updated_at

Obtain a different set of fields using the ?fields= parameter.

Filtering

Filtering is available for the following fields:

id source sourceID name status start_at end_at created_at updated_at

Sorting

By default a collection of reservations is sorted ascending by start_at.

The following fields are accepted by the ?sort= parameter:

id sourceID name start_at end_at created_at updated_at

Get a single reservation

GET /reservations/:id

Response

Status: 200 OK
{
  "ci": {
    "id": 2513,
    "label": "CAR00024",
    "name": "Ford F150 Pickup Truck",
    "nodeID": "..."
  },
  "created_at": "2020-07-11T18:32:42-05:00",
  "end_at": "2020-07-13T23:00:00Z",
  "id": 6,
  "name": "Reserve a pool car",
  "person": {
    "id": 92,
    "name": "Beatrice Baldwin",
    "account": {
      "id": "widget",
      "name": "Widget International"
    },
    "nodeID": "..."
  },
  "preparation_start_at": "2020-07-13T14:30:00Z",
  "request": {
    "id": 80162,
    "subject": "Reserve a pool car",
    "nodeID": "..."
  },
  "reservation_offering": {
    "id": 25,
    "name": "Pool Car",
    "nodeID": "..."
  },
  "source": null,
  "sourceID": null,
  "start_at": "2020-07-13T15:00:00Z",
  "status": "being_prepared",
  "updated_at": "2020-07-13T09:30:59-05:00",
  "nodeID": "..."
}

The response contains these fields.

Create a reservation

POST /reservations

When creating a new reservation these fields are available.

Response

Status: 201 Created
{
  "created_at": "...",
  "...": "..."
}

The response contains all fields of the created reservation and is similar to the response in Get a single reservation

Update a reservation

PATCH /reservations/:id

When updating a reservation these fields are available.

Response

Status: 200 OK
{
  "created_at": "...",
  "...": "..."
}

The response contains all fields of the updated reservation and is similar to the response in Get a single reservation

Fields

ci
Required reference to configuration item — The ID of the related asset.
created_at
Readonly datetime — The date and time at which the reservation was created.
end_at
Required datetime — The End field is used to specify the moment at which the reservation ends.
id
Readonly integer — The unique ID of the reservation.
name
Required string (max 128) — The Name field is used to enter a name for the reservation.
only_this_occurrence
Optional boolean, default: false — Set to true when only this occurrence of a recurrent reservation should be updated. Otherwise this and all future occurrences will be updated.
person
Required reference to Person — The ID of the person for whom the reservation is made.
preparation_start_at
Readonly datetime — The preparation start field is used to specify the moment at which the reservation is being prepared.
recurrence
Optional aggregated — The recurrence settings hash, missing in case the reservation has no recurrency defined. See Recurrence for the fields in the recurrence hash.
reservation_offering
Optional reference to Reservation Offering — The ID of the Reservation offering that was related to the request template used to request the reservation.
request
Optional reference to Request — The ID of the request used to create the reservation.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
start_at
Required datetime — The Start field is used to specify the moment at which the reservation begins.
status
Required enum, default: confirmed — The Status field is used to specify whether a reservation that was requested using the reservation offering is immediately confirmed after it has been submitted, or that an action (such as an approval) is still required before it can be confirmed. Valid values are:
  • provisional: The reservation has been provisionally requested.
  • pending: The reservation has been requested and is awaiting confirmation.
  • confirmed: The reservation is confirmed.
  • being_prepared: The configuration item is being prepared before the start of the reservation.
  • active: The reservation is currently in progress.
  • canceled: The reservation has been canceled.
  • ended: The reservation has already ended.
updated_at
Readonly datetime — The date and time of the last update of the reservation. If the reservation has no updates it contains the created_at value.

Recurrence

The Recurrence record is aggregated within the reservation record in case recurrency is defined for the reservation. It consists of the following fields:

frequency
Readonly enum, default: no_repeat — The frequency of the recurrency.
  • no_repeat: No Repeat
  • daily: Daily
  • weekly: Weekly
  • monthly: Monthly
  • yearly: Yearly
interval
Required integer, default: 1 — The interval of the Frequency, e.g. every 2nd week or every 10th day.
disabled
Optional boolean, default: false — The Disabled box is recurrency should be temporarily disabled.
time_of_day
Required time of day — The time of day to start the scheduled recurrent reservation.
time_zone
Required time_zone — The Time zone field is used to select the time zone for the time_of_day field.
start_date
Required date — The date at which to start the Recurrence.
end_date
Optional date — The date at which to end the Recurrence.
day
Optional stringRequired when frequency is daily, ignored in all other cases. Comma separated list of days of the week, e.g. 1,2,3,4,5.
  • 0: Sunday
  • 1: Monday
  • 2: Tuesday
  • 3: Wednesday
  • 4: Thursday
  • 5: Friday
  • 6: Saturday
day_of_month
Optional stringRequired when frequency is monthly and day_of_week is false, ignored in all other cases. Comma separated list of days of the month, e.g. 11,21,-1.
  • 1: Day one
  • 2: Day two
  • 3: Day three
  • 30: Day thirty
  • 31: Day thirty-one
  • -1: Last day of month
day_of_week
Required boolean, default: false — Indicates whether or not the day_of_week_index and day_of_week_day values should be considered. Can only be set to true when frequency is monthly or yearly.
day_of_week_index
Optional enum, default: firstRequired when day_of_week is true, ignored in all other cases.
  • first: First
  • second: Second
  • third: Third
  • fourth: Fourth
  • last: Last
day_of_week_day
Optional stringRequired when day_of_week is true, ignored in all other cases. Comma separated list of days of the week, e.g. 1,2,3,4,5.
  • monday: Monday
  • tuesday: Tuesday
  • wednesday: Wednesday
  • thursday: Thursday
  • friday: Friday
  • saturday: Saturday
  • sunday: Sunday
month_of_year
Optional stringRequired when frequency is yearly, ignored in all other cases. Comma separated list of months of the year, e.g. 3,6,9,12.
  • 1: January
  • 2: February
  • 3: March
  • 4: April
  • 5: May
  • 6: June
  • 7: July
  • 8: August
  • 9: September
  • 10: October
  • 11: November
  • 12: December
ical
Readonly string (max 2048) - The ICAL representation of the recurrency (without time_of_day)