User Resource

Users are the people who interact with Surpass day to day. Users require a user account with the relevant permissions to allow them to access the specific areas of the system in order to complete their tasks.

User Resource

Below we have listed the operations, HTTP verbs and an example URL for the User resource within the Surpass API.
Operation HTTP Verb Example URL
List GET https://...surpass.com/api/v2/User
Filter GET https://...surpass.com/api/v2/User?$filter=contains(name, 'test')
Read (Individual) GET By ID: https://...surpass.com/api/v2/User/618

By Reference: https://...surpass.com/api/v2/User?reference=jamesl
Create POST https://...surpass.com/api/v2/User/
Update PUT By ID: https://...surpass.com/api/v2/User/618

By Reference: https://...surpass.com/api/v2/User?reference=jamesl
Delete DELETE By ID: https://...surpass.com/api/v2/User/618

By Reference: https://...surpass.com/api/v2/User?reference=jamesl
Attributes for the User Resource

Within the table below we have provided all of the attributes included in the User Resource. This includes the attribute name, data type, if the attribute is orderable when requesting the GET method, if the attribute is available to filter when requesting the GET method, and if the attribute is mandatory when creating a user. Remember that if an attribute is not mandatory it can be omitted from the body of the POST request. 
Attribute Name Type Description Order (GET) Filter (GET) Available Operators (GET) Unique Identifier Mandatory for Create (POST)
id Int The unique identifier for the user. Unable to POST/PUT. eq, gt, it X N/A
reference String This is 'Username in Surpass. X eq, contains X X
href String The link to call the User Resource. Unable to POST/PUT. N/A
firstName String The user's first name. X X eq, contains X
lastName String The user's last name. X X eq, contains X
ssoExternalId String The user's single sign-on external ID. X X eq, contains
email String The user's email address. X X eq, contains X
jobTitle String The user's job title. X X eq, contains
defaultLanguage Enum This controls the language that Surpass will be presented to the user. X X eq
dateCreated DateTime The date the user was created in Surpass. X
retired Boolean The status of the user in Surpass, displays if they are retired or not. X eq N/A
expiryDate DateTime The date at which the user's access to Surpass will expire. X
userPermissions Resource The permissions the user has will be returned when sending a GET request with showPermissions=true. X
Additional Notes
  • UserPermissions contains three fields: centre, subject and permission.
  • We have different logic depending on how these values are set.
  • To grant Site level permissions: Exclude centre and subject.
  • To grant Centre level permissions: Exclude subject only.
  • To grant Subject level permissions: Populate all fields.

GET Request and Return

The GET User resource can be called directly by browsing to the URL, any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the URL that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the User resource. It is important to remember that the return information will be included within the response object that forms part of the standard GET response; this is detailed in the page understanding the Surpass API.

Example GET request & response (JSON)
Example GET request & response (XML)


POST Request and Return

The POST User method requires the attributes listed above to be submitted as part of the body of the request. This can be submitted in either JSON or XML format, the content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request for both formats can be found below.

Depending on how the request was submitted the response will be returned in either JSON or XML format. If the call was unsuccessful then you will receive an error message; all error messages available in the Surpass API can be found here.

Example POST request & response (JSON)
Example POST request & response (XML)


PUT Request and Return

PUT Requests should reference the ID or Reference within the resource. The resource being updated should be included in the body of the request and can be sent in either JSON or XML format. Only the field you want to be updated needs to be included within the request all others can be omitted; these fields will retain their current values. The content-length, content-type and Authorization will also be required in the header of the request.

Example PUT request and response (JSON & XML)


DELETE Request and Return

DELETE Requests should use the ID or Reference of the User you want to delete. Successful deletes will return a status of 200 and will return the base resource with all values set to null. An example of the DELETE User request has been provided below:

Using ID
DELETE https://...surpass.com/api/v2/User/1

Using Reference
DELETE https://...surpass.com/api/v2/User?reference=btljamesl


Required Permissions

To successfully call the User methods, the user specified in the header of the request must have the 'Manage Users' role in Surpass.

Feedback and Knowledge Base