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:
/reservations/open
: List all reservations that are not ended or canceled/reservations/completed
: List all reservations that are ended or canceled
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.