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, ways to filter reservations via GET endpoints, and the input JSON shape used for creating or editing reservations.

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 (Response Shape)

{
  "accessory_users": [],
  "accessory_users_external": [],
  "accessory_users_need_rsvp": boolean,
  "account_number": "string",
  "account_number_description": "string",
  "anonymous": boolean,
  "autocancelled": boolean,
  "blackout": boolean,
  "blocks": [],
  "buffer_before": integer,
  "buffer_start": "string",
  "cancelled": boolean,
  "checked_in": boolean,
  "checked_in_reserved_for": boolean,
  "created": "string",
  "created_by": {},
  "created_unix": integer,
  "currency": "string",
  "currency_code": "string",
  "currency_decimal": "string",
  "currency_thousand": "string",
  "current": boolean,
  "duration": integer,
  "end": "string",
  "end_as_input": "string",
  "end_as_input_for_calendar": "string",
  "end_utc": "string",
  "end_utc_actual": "string",
  "end_utc_unix": integer,
  "form_responses_for_display": [],
  "is_loan": boolean,
  "maintenance": boolean,
  "meta_data": {
    "source": "string"
  },
  "note": "string",
  "original_reservation_created": "string",
  "price": float,
  "price_int": integer,
  "purpose": "string",
  "rate": float,
  "rate_basis": "string",
  "rate_description": "string",
  "rate_id": integer,
  "rate_int": integer,
  "rate_quote_requested": boolean,
  "rate_unit": "string",
  "reminder_seconds": integer,
  "reservable": {},
  "reservation_id": "string",
  "reservation_type": "string",
  "reserved_for": {},
  "reserved_for_supervisor": {},
  "reserved_for_text": "string",
  "returned": "string",
  "site_id": "string",
  "site_name": "string",
  "slim": boolean,
  "soft": boolean,
  "start": "string",
  "start_as_input": "string",
  "start_utc": "string",
  "start_utc_unix": integer,
  "status": "string",
  "template": boolean,
  "total_units": integer,
  "units": integer
}

Reservation Create/Edit Input Object (Request Shape)

This is the JSON shape accepted by reservation create/edit APIs. It is different from the reservation response object above.

Endpoints That Accept This Input

  • POST /reservation
  • POST /reservation/{reservation_id}
  • POST /reservables/{reservable_id}/reserve
  • POST /reservation/template/{template_id}/reserve

Core Validation Rules

  • Request body must be a single JSON object.
  • Time must include exactly one of:
    • duration (seconds), or
    • end (YYYY-MM-DDTHH:MM:SS)
  • start is optional. If omitted, server defaults to current UTC time.
  • start and end format: %Y-%m-%dT%H:%M:%S.
  • start_timestamp (unix integer) can be used instead of start.
  • For editing:
    • pass reservation_id in URL and/or body,
    • if both are present, they must match.
  • for_reservables requires at least 2 items.
  • recurring_reservation_id requires recurring_recipe.
  • maintenance_nonblocking and maintenance_propagates_to_blocked require maintenance=true.
  • meta_data must be a JSON-encoded string (max length 16384), not an object.

Minimal Create Example

{
  "for_reservable_id": "resv_abc123",
  "for_user_id": "usr_123",
  "start": "2026-03-10T09:00:00",
  "duration": 3600,
  "units": 1
}

Minimal Edit Example

{
  "reservation_id": "rsv_456",
  "start": "2026-03-10T10:00:00",
  "duration": 5400,
  "note": "Updated duration"
}

Multi-Resource Example

{
  "for_user_id": "usr_123",  
  "start": "2026-03-10T09:00:00",
  "duration": 3600,
  "for_reservables": [
    { "reservable_id": "resv_a", "units": 1 },
    { "reservable_id": "resv_b", "units": 2 }
  ]
}

Full Top-Level Field List

Field Type Required Notes
for_user_id string No Defaults to logged-in user if omitted
for_user_email string No Used for reservation on behalf of email
for_reservable_id string No Single-resource target
for_reservables list No Multi-resource target; min length 2
reservation_id string No Edit target
recurring_reservation_id string No Edit recurring series (requires recurring_recipe)
recurring_cancel_forward boolean No Edit recurring future behavior
units integer No Defaults to 1; maintenance forces units to 0
named_unit_id string No Named unit selection
start string No %Y-%m-%dT%H:%M:%S
start_timestamp integer No Unix timestamp alternative
end string Conditionally Required if duration omitted
duration integer Conditionally Required if end omitted
purpose string No Reservation purpose
note string No Reservation note
account_number string No Account code
account_id string No Account ID
maintenance_id string No Legacy alias used as reservation ID for maintenance edits
meta_data string No JSON string, max 16384 chars
support_for_reservable_id string No Support-resource linkage
project_ids list[string] No Project links
accessory_users_need_rsvp boolean No Guest RSVP requirement
accessory_user_ids list[string] No Internal guests
accessory_users_external list[object] No External guests
approvers list[object] No Approval overrides
approvers_override_add boolean No Approval behavior
approvers_override_any boolean No Approval behavior
testing boolean No Testing mode
testing_forms boolean No Return form/testing output
testing_price boolean No Return price-testing output
ignore_named_units boolean No Testing helper
template boolean No Template reservation
template_consumable boolean No Template behavior
template_id string No Reserve from template
template_resources_locked boolean No Template behavior
rate_id integer No Selected rate
rate_quote_requested boolean No Quote only behavior
auto_approve_if_self boolean No Approval behavior
autoapprove_note string No Approval note
preserve_approvals boolean No Keep approvals on edit
remove_approvers boolean No Moderator/admin action
silent_approve_approvers boolean No Moderator/admin action
silent_pending_approvers boolean No Moderator/admin action
reserved_for_text string No Bill-to / textual reserved-for
loan boolean No Loan indicator
is_loan boolean No Alias for loan
maintenance boolean No Maintenance reservation
maintenance_nonblocking boolean No Requires maintenance=true
maintenance_propagates_to_blocked boolean No Requires maintenance=true
soft boolean No Soft reservation behavior
return_conflict_end boolean No Legacy/no-op comment in code
reservable_template_id string No Timeless template resource mode
force_reserve boolean No Permission-gated conflict override
allow_auto_deny boolean No Testing/subscription helper
no_send_new_users_emails boolean No Suppress new-user emails
send_user_email boolean No Notification toggle
send_new_guests_email boolean No Notification toggle
admin_note string No Admin note
external_email string No External reservation user email
reminder_seconds integer or null No Reminder lead time
ignore_buffer boolean No Ignore resource buffers
script_id_test string No Script testing only
script_id_test_logged_in_user_id string No Script testing override user
save_recurring_with_conflicts boolean No Recurring conflict behavior
forms list[object] No Form responses
bypass_form_mismatch boolean No Form validation bypass
return_mock_reservation boolean No Return mocked reservation/no commit
return_data_consistent boolean No Paired with mocked-return mode
scripts list[string] No Script IDs
recurring_recipe object No Recurring generation rules

Nested Object Shapes

forms[] item:

{
  "form_id": "string",
  "values": {
      "field_model_id": value,
      "field_model_id": value,
      "field_model_id": value,
      ...
   }
}

accessory_users_external[] item:

{
  "name": "string",
  "email": "guest@example.com"
}

for_reservables[] item:

{
  "reservable_id": "string",
  "units": 1,
  "named_unit_id": "string",
  "rate_id": 123,
  "rate_quote_requested": false,
  "forms": [
    { "form_id": "string", "values": {} }
  ],
  "autoapprove_note": "string",
  "approvers": [
    {
      "approver_site_user_group_id": 1,
      "approver_user_id": "string",
      "automatic": false,
      "show_group_name": false,
      "silent": false,
      "sub_approver_m_of_n": 1,
      "sub_approver_type": "string"
    }
  ],
  "approvers_override_add": false,
  "approvers_override_any": false
}

Top-level rate uses the same shape and allowed values as the nested for_reservables[].rate.

recurring_recipe:

{
  "unit": "weekly",
  "every": 1,
  "until": "2026-06-01",
  "on": [0, 2, 4],
  "cancellations": [1770000000],
  "template_only_for_single_reservations": false,
  "rrule": {
    "frequency": 2,
    "interval": 1,
    "count": 10,
    "byweekday": [0, 2, 4],
    "byhour": [9],
    "byminute": [0],
    "until": 1770000000,
    "wkst": 0,
    "inject_first_date_if_missing": true
  }
}

Behavior Notes (Important)

  • If for_user_id is omitted, the API uses the authenticated user.
  • If start and start_timestamp are both omitted, start defaults to server-side now.
  • For request-type resources, duration=0 can be valid; normal reservables require positive duration.
  • Editing typically works by canceling/replacing the previous reservation record.
  • recurring_cancel_forward=true on recurring edit cancels forward from current instance and creates a new unlinked series.
  • meta_data must be valid JSON text or request fails.

Endpoints

Create or Edit Reservation

POST /reservation
POST /reservation/{reservation_id}
POST /reservables/{reservable_id}/reserve
POST /reservation/template/{template_id}/reserve

Creates a reservation when no reservation_id is supplied, and edits a reservation when reservation_id is supplied (in URL and/or body).

Request Body

Use the Reservation Create/Edit Input Object documented above.

Response

Success Response (200 OK)

Response shape depends on mode:

  • Single non-conflict reservation: returns one reservation object.
  • Multi-resource or recurring/conflict flows: may return an object with:
    • reservations
    • conflicts
  • Includes extra_fields.script_outputs and possibly recurring timestamps in some paths.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: Permission error
  • 404 Not Found: Referenced resource/user/reservation not found
  • 409 Conflict: Conflict or too many recurring reservations

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

Cancel Single Reservation

POST /reservation/{reservation_id}/cancel

Cancels a reservation by its ID. Requires edit and cancellation permission for this reservation.

Request Body

Field Type Required Description
reason string No The reason for the cancellation
silently boolean No Whether to notify the user (requires Moderator or Administrator role)

Response

Success Response (200 OK)

Returns a JSON object:

{
  "maintenance": boolean,
  "reservation_id": "string"
}

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