Staff Management
In Scheduler, staff members are managed in Data > User Management > Users screen. The Users endpoint can be used to list, retrieve, create, and update users; users can be either staff or candidate user accounts.
This article explains what calls can be made to the Scheduler API using the staff management resource.
Import this API into your Postman Workspace
In This Article
Listing staff members
Send a request to the endpoint to retrieve a list of users. Refer to the available parameters to influence the response. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is the token string. |
|
accept |
header MANDATORY |
application/json |
Determines data format of the response, which must be JSON. |
|
take |
query OPTIONAL |
/api/Users?$take={take} |
Defines number of responses to return when paging a response, where {take} is a number between 1 and 150. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in JSON format as requested.
{
"id": "1",
"email": "stuart.fenwick@surpass.com",
"altCalendarSyncEmail": "",
"preferredEmail": null,
"role": "CentreAdmin",
"roleId": "888876d5-c967-4689-b8fe-a7182b7c9272",
"bookerRole": null,
"examRole": null,
"ceremoniesRole": null,
"forename": "Stuart",
"surname": "Fenwick",
"image": null,
"description": null,
"userIndex": 1,
"userType": "Staff",
"userId": "StuartFenwick",
"isInviteReceived": false,
"loginCount": 1,
"isOAuth": false,
"samlSettingsId": null,
"isLockoutEnabled": false,
"lockoutEnd": null,
"isExternalFunded": false,
"tenancyUserId": 1,
"lastLoginDate": "2024-08-28T08:55:00",
"hasAcceptedTerms": false,
"accessArchive": false,
"viewArchive": false,
"parentDepartmentIds": [],
"parentDepartments": [],
"departmentIds": [
1
],
"departments": [
{
"colour": null,
"parentId": null,
"parent": null,
"isEligibilityEnabled": false,
"allowAnonymousBookingView": false,
"isPORequired": false,
"ownerIds": null,
"owners": null,
"staffDepartments": null,
"roomDepartments": null,
"buildingDepartments": null,
"studentDepartments": null,
"departmentEnrolmentResultTypes": null,
"childDepartments": null,
"edit": false,
"delete": false,
"hideInLists": false,
"customFields": null,
"id": "1",
"description": "User1",
"altId": null,
"optimeIndex": 1,
"createUser": null,
"createDate": null,
"changeUser": null,
"changeDate": null,
"messages": []
}
],
"courseTypeIds": [],
"courseTypes": [],
"moduleTypeIds": [],
"moduleTypes": [],
"language": "en",
"twoFactorEnabled": false,
"edit": false,
"insert": false,
"delete": false,
"createUser": null,
"createDate": null,
"changeUser": "stuart.fenwick@surpass.com",
"changeDate": "2024-08-28T09:55:00",
"messages": []
}
...Response schema
The response schema contains a description of various properties that can be returned for this endpoint. For a full API reference, contact your Surpass Customer Success Manager.
id string
The staff member’s unique reference code, , which is equivalent to an optimeIndex identifier.
email string
The staff member’s email address.
role enumeration
The user’s role, which is one of Staff or Student (candidate user account).
roleId string
The role’s unique reference code.
forename string
The staff member’s first name.
surname string
The staff member’s surname.
userType enumeration
The user’s user type, which is one of Staff or Student (candidate user account).
lastLoginDate string
The date the staff member last logged in, in YYYY-MM-DDTHH:MM:SS format.
departmentIds array
The unique OptimeIndex identifiers of any departments the staff member is registered at.
departments array
Contains information for the departments the staff member is registered at.
departments/id string
The department’s unique reference code.
departments/description string
A descriptive code for the department, similar to a unique reference code.
departments/optimeIndex integer
The department’s unique OptimeIndex identifier.
twoFactorEnabled Boolean
Determines whether Two-Factor Authentication (2FA) is enabled (true) or not (false).
Retrieving staff member information
Send a request to the endpoint to retrieve information for a specific staff member using their ID. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is the token string. |
|
accept |
header MANDATORY |
application/json |
Determines data format of the response, which must be JSON. |
|
id |
path OPTIONAL |
/api/Users/{userId} |
Returns information for the specified staff member, where {userId} is the staff member’s unique reference code. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in JSON format as requested.
{
"id": "1",
"email": "stuart.fenwick@surpass.com",
"altCalendarSyncEmail": "",
"preferredEmail": null,
"role": "CentreAdmin",
"roleId": "888876d5-c967-4689-b8fe-a7182b7c9272",
"bookerRole": null,
"examRole": null,
"ceremoniesRole": null,
"forename": "Stuart",
"surname": "Fenwick",
"image": null,
"description": null,
"userIndex": 1,
"userType": "Staff",
"userId": "StuartFenwick",
"isInviteReceived": false,
"loginCount": 1,
"isOAuth": false,
"samlSettingsId": null,
"isLockoutEnabled": false,
"lockoutEnd": null,
"isExternalFunded": false,
"tenancyUserId": 1,
"lastLoginDate": "2024-08-28T08:55:00",
"hasAcceptedTerms": false,
"accessArchive": false,
"viewArchive": false,
"parentDepartmentIds": [],
"parentDepartments": [],
"departmentIds": [
1
],
"departments": [
{
"colour": null,
"parentId": null,
"parent": null,
"isEligibilityEnabled": false,
"allowAnonymousBookingView": false,
"isPORequired": false,
"ownerIds": null,
"owners": null,
"staffDepartments": null,
"roomDepartments": null,
"buildingDepartments": null,
"studentDepartments": null,
"departmentEnrolmentResultTypes": null,
"childDepartments": null,
"edit": false,
"delete": false,
"hideInLists": false,
"customFields": null,
"id": "1",
"description": "User1",
"altId": null,
"optimeIndex": 1,
"createUser": null,
"createDate": null,
"changeUser": null,
"changeDate": null,
"messages": []
}
],
"courseTypeIds": [],
"courseTypes": [],
"moduleTypeIds": [],
"moduleTypes": [],
"language": "en",
"twoFactorEnabled": false,
"edit": false,
"insert": false,
"delete": false,
"createUser": null,
"createDate": null,
"changeUser": "stuart.fenwick@surpass.com",
"changeDate": "2024-08-28T09:55:00",
"messages": []
}Response schema
The response schema contains a description of various properties that can be returned for this endpoint. For a full API reference, contact your Surpass Customer Success Manager.
id string
The staff member’s unique reference code, which is equivalent to an optimeIndex identifier.
email string
The staff member’s email address.
role enumeration
The user’s role, which is one of Staff or Student (candidate user account).
roleId string
The role’s unique reference code.
forename string
The staff member’s first name.
surname string
The staff member’s surname.
userType enumeration
The user’s user type, which is one of Staff or Student (candidate user account).
lastLoginDate string
The date the staff member last logged in, in YYYY-MM-DDTHH:MM:SS format.
departmentIds array
The unique OptimeIndex identifiers of any departments the staff member is registered at.
departments array
Contains information for the departments the staff member is registered at.
departments/id string
The department’s unique reference code.
departments/description string
A descriptive code for the department, similar to a unique reference code.
departments/optimeIndex integer
The department’s unique OptimeIndex identifier.
twoFactorEnabled Boolean
Determines whether Two-Factor Authentication (2FA) is enabled (true) or not (false).
Creating a staff member
Send a request to the endpoint to create a staff member.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is the token string. |
|
content-type |
header MANDATORY |
application/json |
Determines data format of the request, which must be JSON. |
|
accept |
header MANDATORY |
application/json |
Determines data format of the response, which must be JSON. |
Sample request
The following is a sample request body to create a staff member.
{
"email": "stuart.fenwick@surpass.com",
"role": "CentreAdmin",
"forename": "Stuart",
"surname": "Fenwick",
"userType": "Staff",
"departmentIds": [1],
"isOAuth": false
}Request body schema
The request body schema contains a description of various properties that can be passed with this endpoint. For a full API reference, contact your Surpass Customer Success Manager.
email string
The staff member’s email address.
role enumeration
The user’s role, which is one of Staff or Student (candidate user account).
forename string
The staff member’s first name.
surname string
The staff member’s surname.
userType enumeration
The user’s user type, which is one of Staff or Student (candidate user account).
departmentIds array
The unique OptimeIndex identifiers of any departments the staff member is registered at.
is0Auth Boolean
Determines whether Single Sign-On (SSO) is enabled (true) or not (false). Defaults to false if omitted.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new staff member’s details.
{
"id": "1",
"email": "stuart.fenwick@surpass.com",
"altCalendarSyncEmail": null,
"preferredEmail": null,
"role": "Student",
"roleId": "1",
"bookerRole": null,
"examRole": null,
"ceremoniesRole": null,
"forename": "Stuart",
"surname": "Fenwick",
"image": null,
"description": null,
"userIndex": 1,
"userType": "Staff",
"userId": "1",
"isInviteReceived": false,
"loginCount": 0,
"isOAuth": false,
"samlSettingsId": null,
"isLockoutEnabled": false,
"lockoutEnd": null,
"isExternalFunded": false,
"tenancyUserId": 1,
"lastLoginDate": null,
"hasAcceptedTerms": false,
"accessArchive": false,
"viewArchive": false,
"parentDepartmentIds": [],
"parentDepartments": [],
"departmentIds": [
1
],
"departments": [
{
"colour": null,
"parentId": null,
"parent": null,
"isEligibilityEnabled": false,
"allowAnonymousBookingView": false,
"isPORequired": false,
"ownerIds": null,
"owners": null,
"staffDepartments": null,
"roomDepartments": null,
"buildingDepartments": null,
"studentDepartments": null,
"departmentEnrolmentResultTypes": null,
"childDepartments": null,
"edit": false,
"delete": false,
"hideInLists": false,
"customFields": null,
"id": "SurpassDepartment",
"description": "Surpass Department",
"altId": null,
"optimeIndex": 1,
"createUser": null,
"createDate": null,
"changeUser": null,
"changeDate": null,
"messages": []
}
],
"courseTypeIds": [],
"courseTypes": [],
"moduleTypeIds": [],
"moduleTypes": [],
"language": null,
"twoFactorEnabled": false,
"edit": true,
"insert": true,
"delete": true,
"createUser": "stuart.fenwick@surpass.com",
"createDate": "2025-06-10T12:08:00",
"changeUser": null,
"changeDate": null,
"messages": []
}Updating a staff member
Send a request to the endpoint to update a specific staff member.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is the token string. |
|
content-type |
header MANDATORY |
application/json |
Determines data format of the request, which must be JSON. |
|
accept |
header MANDATORY |
application/json |
Determines data format of the response, which must be JSON. |
|
id |
path MANDATORY |
/api/Users/{userId} |
Update specified staff member, where {id} is the staff member’s unique reference code. |
Sample request
At least one property must be updated in the request. The following is a sample request body to update a staff member. Refer to the request body schema for more properties that can be updated.
{
"email": "fenwick.stuart@surpass.com",
"role": "Staff",
"forename": "Stuart",
"surname": "Fenwick",
"userType": "Staff",
"departmentIds": [1],
"isOAuth": false
}Request body schema
The request body schema contains a description of various properties that can be passed with this endpoint. For a full API reference, contact your Surpass Customer Success Manager.
email string
The staff member’s email address.
role enumeration
The user’s role, which is one of Staff or Student (candidate user account).
forename string
The staff member’s first name.
surname string
The staff member’s surname.
userType enumeration
The user’s user type, which is one of Staff or Student (candidate user account).
departmentIds array
The unique OptimeIndex identifiers of any departments the staff member is registered at.
is0Auth Boolean
Determines whether Single Sign-On (SSO) is enabled (true) or not (false).
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated staff member’s details.
{
"id": "1",
"email": "fenwick.stuart@surpass.com",
"altCalendarSyncEmail": null,
"preferredEmail": null,
"role": "Staff",
"roleId": "1",
"bookerRole": null,
"examRole": null,
"ceremoniesRole": null,
"forename": "Stuart",
"surname": "Fenwick",
"image": null,
"description": null,
"userIndex": 1,
"userType": "Staff",
"userId": "1",
"isInviteReceived": false,
"loginCount": 0,
"isOAuth": false,
"samlSettingsId": null,
"isLockoutEnabled": false,
"lockoutEnd": null,
"isExternalFunded": false,
"tenancyUserId": 1,
"lastLoginDate": null,
"hasAcceptedTerms": false,
"accessArchive": false,
"viewArchive": false,
"parentDepartmentIds": [],
"parentDepartments": [],
"departmentIds": [
1
],
"departments": [
{
"colour": null,
"parentId": null,
"parent": null,
"isEligibilityEnabled": false,
"allowAnonymousBookingView": false,
"isPORequired": false,
"ownerIds": null,
"owners": null,
"staffDepartments": null,
"roomDepartments": null,
"buildingDepartments": null,
"studentDepartments": null,
"departmentEnrolmentResultTypes": null,
"childDepartments": null,
"edit": false,
"delete": false,
"hideInLists": false,
"customFields": null,
"id": "SurpassDepartment",
"description": "Surpass Department",
"altId": null,
"optimeIndex": 1,
"createUser": null,
"createDate": null,
"changeUser": null,
"changeDate": null,
"messages": []
}
],
"courseTypeIds": [],
"courseTypes": [],
"moduleTypeIds": [],
"moduleTypes": [],
"language": null,
"twoFactorEnabled": false,
"edit": true,
"insert": true,
"delete": true,
"createUser": "stuart.fenwick@surpass.com",
"createDate": "2025-06-10T12:08:00",
"changeUser": null,
"changeDate": null,
"messages": []
}Further reading
Read the following articles to learn more about the scheduling system or more about related APIs: