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.