Documentation

Site Users API

Table of Contents

Overview

Users in QReserve have a core user account that includes information about authentication, email, and name. Each user can be a member of one or more sites in QReserve that encases the user object in a SiteUser object where additional, site-specific information can be included such as role, account numbers, and custom site properties.

Typically an action performed in QReserve by a user is linked to a User object and from that a corresponding SiteUser object can be obtained for that user by finding the SiteUser object for a particular User and Site combination.

For convenience, adding users to your site can automatically handle the just-in-time creation of the core user account as well; however, a site administrator does not have the capability to delete a core user account but only to remove that account from their site. Site administrators can edit the name of users who are only members of sites they administer and they can edit emails of users who have not yet logged in.

Data Structures

SiteUser Object

{
  "site_user_id": "string",
  
  "user": {},                         // Core user object
  "active": boolean,
  
  "role": "user|moderator|administrator",
  
  "roles": {                          // Additional roles that can be provided to regular users
    "reservation_creator": boolean,   // Coming soon
    "reservation_editor": boolean
  },
  
  "account_numbers": [
    {
      "account_number": "string",
      "description": "string"
    },
    ...
  ],
  
  "actual_usage_identifiers": [
    {
      "identifier": "string",
      "description": "string"
    },
    ...
  ],
  
  "barcode": "string",
  "billing_address": "string",
  
  "exclude_from_activity_report": boolean,
  
  "hidden_note": "string",
  
  "ignore_min_max_times": boolean,
  "joinedsite": "string",             // Datetime
  "last_access": "string",            // Datetime
  
  "properties": [],                   // Array of Property objects
  "qrid": "string",
  
  "supervisor": {},                   // User object or null
  
  "approves": {                       // Things this user approves
    "reservables": [],                // Array of Reservable objects
    "users": []                       // Array of User objects
  },
  
  "approvers": [],                    // Array of User objects (people who approve this user)
  
  "cc_multiuse_token_available": boolean,  // If possible to add a payment method
  "cc_multiuse_token_exists": boolean,
  
  "training_records": [],             // Array of CredentialRecord objects
  
  "usergroups": [],                   // Array of UserGroup objects
  
  "can_edit_email": boolean,          // Edit capability flags for administrators
  "can_edit_name": boolean
}

User Object

{
  "user_id": "string",
  
  "is_admin_bot": boolean,            // Single automatically created admin account
  "is_user_bot": boolean,             // Standard test or bot accounts
  
  "affiliation": "string",
  "authenticatable": boolean,
  "description": "string",
  "display_name": "string",
  "email": "string",
  "expertise": "string",
  "givennames": "string",
  "image": "string",
  "image_is_default": boolean,
  "image_thumb": "string",
  "lastname": "string",
  "phone": "string",
  "site_role": "user|moderator|administrator",
  "twitter": "string",
  "unsubscribed": boolean,
  "verified": boolean,
  "website": "string"
}

UserGroup Object

{
  "name": "string",
  "color": "string",
  "reservation_visibility": boolean,
  "usergroup_id": integer
}

Endpoints

List Site Users

GET /sites/{site_id}/users

Retrieves a list of users for a site.

Path Parameters

Parameter Type Required Description
site_id string Yes ID of the site to retrieve users from

Query Parameters

Parameter Type Default Description
slim boolean false Return fewer fields
slim_reservables boolean false Return slimmer reservable objects when included
limit integer null Number of results to return
offset integer null Offset row to start at
email string null Filter users by email (matches exact only)
search string null Filter users by name and email (matches substrings)
usergroup integer null Usergroup ID to filter by
supervisor_id string null User ID of the supervisor to filter by
user_bots_only boolean false Only return bots or test users

Response

Success Response (200 OK)

Returns a list of SiteUser objects matching the query parameters.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to view site users

Get Single Site User

GET /sites/{site_id}/users?user_id={user_id}

Retrieves a specific site user by their user ID.

Path Parameters

Parameter Type Required Description
site_id string Yes ID of the site

Query Parameters

Parameter Type Required Description
user_id string Yes ID of the user to retrieve

Response

Success Response (200 OK)

Returns a SiteUser object.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to view this site user
  • 404 Not Found: User with the specified ID does not exist on this site

Create Site User

POST /sites/{site_id}/adduser

Creates a new site user, which may include creating a new core user account if the email is not already associated with an existing user.

Path Parameters

Parameter Type Required Description
site_id string Yes ID of the site where the user will be added

Request Body

Required Fields

Field Type Required Description
email string Yes Email address of the user
role string Yes Role of the user on this site (one of: user, moderator, administrator)

Optional Fields

Field Type Required Description
display_name string No Display name of the user
givennames string No Given names of the user
surname string No Surname of the user
usergroups array of integers No List of usergroup IDs to add the user to
notify_user boolean No Whether to notify the user
notify_user_admin boolean No Whether to notify the site owner if enabled in the site
message string No Message to include in user notification

Response

Success Response (200 OK)

Returns the newly created SiteUser object.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to add users to this site

Update Site User

POST /sites/{site_id}/users/{user_id}

Updates an existing site user.

Path Parameters

Parameter Type Required Description
site_id string Yes ID of the site
user_id string Yes ID of the user to update

Request Body

Optional Fields

Field Type Required Description
usergroups array of integers No List of usergroup IDs to set for the user
... ... No Many other fields are supported

Note: For a full list of options at this time, we recommend setting a value of a Site User from the user interface and observing the field being set via Developer Tools in your browser.

Response

Success Response (200 OK)

Returns the updated SiteUser object.

Error Responses

  • 400 Bad Request: Invalid request or validation error
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: User does not have permission to update this site user
  • 404 Not Found: User with the specified ID does not exist on this site