Documentation

Reservations API

Table of Contents

Overview

Reservations form a core component of data in QReserve and as a result their API can be quite complex and varied depending on particular use cases. This documentation provides an overview of what a reservation object looks like and ways to filter reservations via GET endpoints.

For example use cases, we recommend using the QReserve web application, visiting a calendar page, and then playing with the available filters to observe how the different fields are utilized and the types of responses returned.

Data Structure

Reservation Object

{
  "accessory_users": [],                  // List of users added as accessories (guests)
  "accessory_users_external": [],         // List of external accessories (guests)
  "accessory_users_need_rsvp": boolean,   // Whether accessory users need to RSVP
  "account_number": "string",             // The account number associated with this reservation
  "account_number_description": "string", // A description of the account number
  "anonymous": boolean,                   // Whether this reservation is anonymous due to user permissions
  "autocancelled": boolean,               // Whether this reservation has been automatically cancelled
  "blackout": boolean,                    // Whether this reservation is a blackout period (weekly block)
  "blocks": [],                           // List of resources this reservation blocks
  "buffer_before": integer,               // Amount of time before start that should be buffered
  "buffer_start": "string",               // Start date/time of buffer period (ISO format)
  "cancelled": boolean,                   // Whether this reservation has been cancelled
  "checked_in": boolean,                  // Whether any user has checked into this reservation
  "checked_in_reserved_for": boolean,     // Whether reserved_for user has checked in
  "created": "string",                    // Date/time when reservation was created (ISO format)
  "created_by": {},                       // User object who created the reservation
  "created_unix": integer,                // Unix timestamp when reservation was created
  "currency": "string",                   // Currency symbol
  "currency_code": "string",              // ISO code for the currency
  "currency_decimal": "string",           // Decimal separator used in the currency
  "currency_thousand": "string",          // Thousands separator used in the currency
  "current": boolean,                     // Whether reservation is current (happening at time of request)
  "duration": integer,                    // Length of time in seconds
  "end": "string",                        // End date/time (ISO format)
  "end_as_input": "string",               // End time formatted for creating/editing
  "end_as_input_for_calendar": "string",  // End time formatted for calendar
  "end_utc": "string",                    // End date/time in UTC (ISO format)
  "end_utc_actual": "string",             // End time of scheduled reservation (may differ for overdue loans)
  "end_utc_unix": integer,                // Unix timestamp for end time (UTC)
  "form_responses_for_display": [],       // List of form responses for calendar display
  "is_loan": boolean,                     // Whether this is a loan
  "maintenance": boolean,                 // Whether this is a maintenance reservation
  "meta_data": {
    "source": "string"
  },
  "note": "string",                       // Note associated with this reservation
  "original_reservation_created": "string", // Creation date of original reservation (ISO format)
  "price": float,                         // Price of this reservation
  "price_int": integer,                   // Price in cents
  "purpose": "string",                    // Purpose of this reservation
  "rate": float,                          // Rate charged
  "rate_basis": "string",                 // Basis for the rate (e.g. per unit)
  "rate_description": "string",           // Description of the rate
  "rate_id": integer,                     // ID of the rate
  "rate_int": integer,                    // Rate in cents
  "rate_quote_requested": boolean,        // Whether a rate quote was requested
  "rate_unit": "string",                  // Unit for the rate (e.g. per hour)
  "reminder_seconds": integer,            // Seconds before reservation to send reminder
  "reservable": {},                       // Reservable object
  "reservation_id": "string",             // ID of this reservation
  "reservation_type": "string",           // Type of reservation
  "reserved_for": {},                     // User object reservation is for
  "reserved_for_supervisor": {},          // Supervisor user object
  "reserved_for_text": "string",          // Name/description of user reservation is for
  "returned": "string",                   // Date/time when marked returned (for loans)
  "site_id": "string",                    // ID of associated site
  "site_name": "string",                  // Name of associated site
  "slim": boolean,                        // Whether this is a slim response
  "soft": boolean,                        // When true, won't raise conflict with overlapping reservations
  "start": "string",                      // Start date/time (ISO format)
  "start_as_input": "string",             // Start time formatted for creating/editing
  "start_utc": "string",                  // Start date/time in UTC (ISO format)
  "start_utc_unix": integer,              // Unix timestamp for start time (UTC)
  "status": "string",                     // Status of reservation (e.g. pending)
  "template": boolean,                    // Whether this is a template slot
  "total_units": integer,                 // Total units available when reservation was made
  "units": integer                        // Units booked for this reservation
}

Endpoints

List Reservations

GET /reservationssite

This endpoint is optimized for retrieving multiple reservations at once and as a result may not have all fields fully populated. To retrieve a full reservation, you can request it via the "Get Single Reservation" endpoint using the reservation_id.

Query Parameters

Parameter Type Default Description
and_requests boolean false Whether to include requests in addition to reservations
barcode string "" Filter by barcode
category string "" Filter by category (does substring matching on display category field)
current_only boolean false Only return current reservations (happening at the time of the request)
end string "" Filter by end date/time
end_unix integer 0 Filter by end Unix timestamp
filter_time string "" How to filter by time - blank means any overlap, 'start' means starts in filtered times, and 'end' means end in filtered times
for_logged_in_user boolean false Whether to filter by the currently logged-in user
for_site_calendar boolean false Whether to return data for a site calendar (may have different fields)
include_approvals boolean false Whether to include approvals in the response
include_autocancelled boolean false Whether to include autocanceled reservations
include_blocked boolean true Whether to include resources that each reservation blocks
include_cancelled boolean false Whether to include canceled reservations
include_cancelled_and_edited boolean false Whether to include both canceled and edited reservations
include_checked_in boolean true Whether to include reservations that are explicitly checked into or out of
include_checked_in_status boolean true Whether to include the checked-in status of reservables
include_events boolean false Whether to include events in the response
include_event_requests boolean true Whether to include event requests
include_filtered_user_if_guest boolean true Whether to include a filtered user if they are a guest
include_form_responses boolean false Whether to include form responses in the response
include_ical_feeds boolean true Whether to include iCal feed reservations
include_maintenance boolean false Whether to include maintenance reservables
include_maintenance_nonblocking boolean false Whether to include non-blocking maintenance reservables
include_not_checked_in boolean true Whether to include not checked-in reservables
include_paid_status boolean false Whether to include paid status in the response
include_projects boolean true Whether to include projects in the response
include_soft boolean true Whether to include soft reservables
include_templates boolean false Whether to include templates in the response
invoice_id string "" Filter by invoice ID
is_loan boolean false Whether to filter by loan status
is_returned boolean false Whether to filter by returned status
is_overdue boolean false Whether to filter by overdue status
limit integer none Limit the number of results
offset integer none The offset of the first item in the result set
only_events boolean false Whether to only return events
only_maintenance boolean false Whether to only return maintenance reservations
only_maintenance_nonblocking boolean false Whether to only return non-blocking maintenance reservations
only_soft boolean false Whether to only return soft reservations
only_templates boolean false Whether to only return template reservations
order_by_attr string null The attribute to order the results by
order_by_desc boolean false Whether to order the results in descending order
paid_status boolean false Whether to only return paid reservations
pinned_to_project boolean false Whether to only return reservations pinned to a project
portal_id string null The ID of the portal to filter by
project_id string null The ID of the project to filter by
qclass string null The class of the reservations to filter by
rate_meta_data_query string null A query to filter rate meta data by
rate_meta_data_query_path array [] A path to filter rate meta data by
rate_requests_only boolean false Whether to only return rate requests
read_only boolean false Whether the reservation is read-only
recurring_reservation_id string null The ID of the recurring reservation to filter by
requests_only boolean false Whether to only return requests
requests_time_filter_attr string null An attribute to filter request time by
reservable_id string null The ID of the reservable item to filter by
reservable_ids array [] A list of IDs of reservable items to filter by
reservable_site_ordinal_ids array [] A list of site ordinal IDs of reservable items to filter by
reservation_ids array [] A list of IDs of reservations to filter by
return_count boolean false Whether to return the count of results
return_only_count boolean false Whether to only return the count of results
search_form_responses string null A query to search form responses by
search_reservation string null A query to search reservations by
site_id string null The ID of the site to filter by
skip_executing_visibility_scripts boolean false Whether to skip executing visibility scripts
start string null The start date of the reservations to filter by
start_unix integer none The start time of the reservations to filter by in Unix format
statuses array [] A list of statuses to filter by
supervisor_id string null The ID of the supervisor to filter by
tags array [] A list of tags to filter by
user_id string null The ID of the user to filter by
usergroup_id integer none The ID of the user group to filter by
verbose_checked_in boolean false Whether to return verbose checked-in information

Response

Success Response (200 OK)

Returns a list of reservation objects matching the query parameters.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed

Get Single Reservation

GET /reservations/{reservation_id}

Retrieves a complete reservation object by its ID.

Path Parameters

Parameter Type Required Description
reservation_id string Yes ID of the reservation to retrieve

Response

Success Response (200 OK)

Returns a complete reservation object.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 404 Not Found: Reservation with the specified ID does not exist