Documentation

Actual Usage API

Table of Contents

Overview

The Actual Usage module allows you to track time used on equipment or resources and manage check-ins and check-outs to reservations.

Endpoints

Get Actual Usage Data

GET /actualusage

Retrieves actual usage data for a site.

Query Parameters

Parameter Type Required Description
site_id string Yes Site ID to retrieve actual usage data for
reservable_ids array of strings No IDs of reservables to filter by
tags array of strings No Tags to filter by
limit integer No Maximum number of records to return
offset integer No Offset for pagination
start date (YYYY-MM-DD) No Start date for record filter
end date (YYYY-MM-DD) No End date for record filter
user_id string No IDs of users to filter by
supervisor_id string No IDs of user supervisor to filter by
identifier string No Actual usage identifier of users to filter by
barcode string No Barcode of resources to filter by
category string No Category of resources to filter by
has_reservation boolean No Filter records by those that have a reservation associated
merge_threshold integer No When specified, merge actual usage records together for the same user and resource if the gap between the end and start time is less than or equal to the merge threshold value
open_session boolean No Filter records by those that do or do not have an open session (no specified end time)
incl_invoices boolean No Whether to include invoices in the response

Response

Success Response (200 OK)

{
  "records": [
    // List of actual usage records
  ],
  "metrics": [
    // List of available metrics
  ],
  "numitems": 150 // Total number of records (may be more than returned due to pagination)
}

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User is not a site moderator
  • 404 Not Found: Site with the specified ID does not exist

Create/Update/Delete Actual Usage Entry

POST /actualusage

Create a new usage entry, update an existing one, or delete an entry. This endpoint supports both complete entries (with start and end time) and sessioned entries (with an open_session post followed by a close_session post).

Note: Please also refer to the advanced usage instructions for interacting with individual resources via the API. This can be found on the Actual Usage tab of a resource when editing it in QReserve.

Request Body

Field Type Required Description
start number (float/integer) No Start timestamp
end number (float/integer) No End timestamp
source string Yes Source of the actual usage entry
in_use boolean Yes Whether the resource is in use
metrics object No Additional metrics for the actual usage entry
require_user boolean No Whether a user is required for this actual usage entry
ignore_user boolean No Whether to ignore the user for this actual usage entry
use_res_user boolean No Whether to use the user from the reservation
reservable_id string No ID of the reservable resource
api_key string No API key for authentication
reservation_id string No ID of the reservation
user_id string No ID of the user
user_email string No Email of the user
user_identifier string No Identifier for the user
open_session boolean No Whether to open a new session
auto_end integer No Auto-end timestamp for the session
update_session boolean No Whether to update an existing session
close_session boolean No Whether to close an existing session
delete boolean No Whether to delete an actual usage entry
return_data boolean No Whether to return data in the response

Path Parameters

Parameter Type Required Description
actual_usage_string_id string No ID of the actual usage entry to update or delete

Response

Success Response (200 OK)

Response depends on the operation and whether return_data is set to true.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission for this operation
  • 404 Not Found: Actual usage entry with the specified ID does not exist

Batch Operations: This endpoint can accept a list of actual usage entries in the request body. The response will contain a list of created, updated, or deleted actual usage entries.

Check In To a Reservation

POST /reservations/{reservation_id}/checkin

Checks in to a reservation with the specified ID.

Request Body

Field Type Required Description
allow_multiple boolean No Whether to allow multiple check-ins after this initial one
auto_end boolean No Whether to automatically end the reservation after a certain delay as set on the resource
source string No The source of the check-in
metrics object No Additional metrics to record with the check-in
return_data boolean No Whether to return data about the created actual usage record

Path Parameters

Parameter Type Required Description
reservation_id string Yes The ID of the reservation to check in

Response

Success Response (200 OK)

If return_data is true, response body contains data about the created actual usage record.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to check in this reservation
  • 404 Not Found: Reservation with the specified ID does not exist

Check Out of a Reservation

POST /reservations/{reservation_id}/checkout

Checks out of a reservation with the specified ID.

Request Body

Field Type Required Description
return_data boolean No Return data after checking out (default: false)

Query Parameters

Parameter Type Required Description
return_data boolean No Return data after checking out

Path Parameters

Parameter Type Required Description
reservation_id string Yes Reservation ID to check out

Response

Success Response (200 OK)

If return_data is true, response body contains the checked-out reservation data.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to check out this reservation
  • 404 Not Found: Reservation with the specified ID does not exist