Documentation

Credentials API

Table of Contents

Overview

Credentials in QReserve are records associated with users within a site or a portal that may or may not have an expiry date. Credentials can be used to restrict access to resources, filter users for messaging, or be used in reservation and rate scripts to make decisions.

Note: Credentials were historically referred to as training within QReserve. For backwards compatibility, many API names still refer to training instead of credentials. This API is undergoing a transitional period.

Credential Types

A credential type is a class of records a person can earn. For example, it could be a specific type of training, a membership, or a status. Each credential record is a record of a particular credential type.

Data Structure

{
    "training_id": "string",
    "active": boolean,
    "name": "string",
    "description": "string",
    "site_id": "string" | null,
    "site_name": "string" | null,
    "portal_id": "string" | null,
    "portal_name": "string" | null,
    "duration_default": integer | null,
    "duration_default_unit": "years" | "months" | "weeks" | "days" | "minutes" | "seconds",
    "reservables": [
        // Resource objects restricted to requiring this credential
    ],
    "silent": boolean,
    "user_name_affix": "string" | null,
    "training_records": [
        // Credential record objects (only if requested)
    ]
}

List Credential Types

GET /sites/{site_id}/training
GET /portals/{portal_id}/training

Path Parameters

Parameter Type Required Description
site_id string Yes ID of the site (for first endpoint)
portal_id string Yes ID of the portal (for second endpoint)

Query Parameters

Parameter Type Default Description
active boolean true Set to false to return deactivated credential types
excludes_portal boolean false When requesting site level credential types, any types inherited from a portal will be included unless this is set to true
include_records boolean false Populates the training_records array in each Credential object

Get Single Credential Type

GET /training/{training_id}

Path Parameters

Parameter Type Required Description
training_id string Yes ID of the credential type to retrieve

Create Credential Type

POST /training

Request Body

Required Fields

Field Type Required Description
name string Yes Name of the credential type
site_id string No* ID of the site
portal_id string No* ID of the portal

* You must include either site_id OR portal_id, but not both.

Optional Fields

Field Type Default Description
description string Description of the credential type
duration_default integer Default duration for credentials of this type
duration_default_unit string Unit for the default duration ("years", "months", "weeks", "days", "minutes", "seconds")
user_name_affix string Text to display next to user names with this credential
never_expires boolean Whether credentials of this type never expire
silent boolean Whether to suppress notifications

Update Credential Type

POST /training/{training_id}

Path Parameters

Parameter Type Required Description
training_id string Yes ID of the credential type to update

Request Body

Optional Fields

Field Type Description
name string Name of the credential type
description string Description of the credential type
duration_default integer Default duration for credentials of this type
duration_default_unit string Unit for the default duration
active boolean Whether the credential type is active
user_name_affix string Text to display next to user names with this credential
never_expires boolean Whether credentials of this type never expire
silent boolean Whether to suppress notifications

Credential Records

A credential record is an instance of a credential type for a user in your site. A record will be considered valid from the moment it is created up until its (optional) expiry date. Additional information can be stored in the meta_data JSON field that is accessible in sneq scripts.

Data Structure

{
    "user_training_record_id": "string",
    "training_id": "string",
    "user": {
        // User object
    },
    "portal_id": "string" | null,
    "portal_name": "string" | null,
    "site_id": "string" | null,
    "site_name": "string" | null,
    "added_by": {
        // User object
    },
    "created": "UTC date string",
    "days_left": integer | null,  // Days until expires
    "earned_on": "string",  // Typically date but supports arbitrary text
    "expired": boolean,  // True when now() > expires
    "expires": "date string",
    "name": "string",  // Credential Type name
    "note": "string",
    "performed_by": "string",
    "silent": boolean,
    "meta_data": JSON object | null
}

List Credential Records

GET /training/records

Required Query Parameters (One or more required)

Parameter Type Required Description
user_training_record_id string No* Specific training record ID
site_id string No* Records for users within this site
portal_id string No* Records for users within this portal
training_id string No* Records for users for this credential type

* At least one of these parameters is required.

Optional Query Parameters

Parameter Type Default Description
newest_only boolean false Only return the most recent record for each user
expiring boolean false Only return the records set to expire in the next 30 days
return_count boolean false Include a total count in the numitems field of the root return object
limit integer 100 Maximum number of records to return
offset integer 0 Combine with limit to offset the first record in the returned list

Create Credential Record

POST /training/record_add/{training_id}

Path Parameters

Parameter Type Required Description
training_id string Yes ID of the credential type

Request Body

Required Fields

Field Type Required Description
user_id string No* ID of the user to add the credential to
user_ids array of strings No* IDs of multiple users to add the credential to

* You must include either user_id OR user_ids, but not both.

Optional Fields

Field Type Default Description
expires date string Expiration date for the credential
note string Note associated with the credential
performed_by string Who performed or issued the credential
earned_on string When the credential was earned
silent boolean Credential type default Whether to suppress notifications
expire_old boolean true Whether to expire old records for this user and credential
meta_data JSON object Additional metadata for the credential
return_data boolean false Whether to return the created record in the response

Expire Credential Record

Mark a training record as expired immediately. Record will be visible to a user on their history page.

POST /training/record/{user_training_record_id}/expire

Path Parameters

Parameter Type Required Description
user_training_record_id string Yes ID of the credential record to expire

Request Body

Empty object {}

Delete Credential Record

Mark a training record as deleted immediately. Record will not be visible to a user on their history page.

POST /training/record/{user_training_record_id}/delete

Path Parameters

Parameter Type Required Description
user_training_record_id string Yes ID of the credential record to delete

Request Body

Empty object {}