User Resource
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 |
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 | ||
| 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 |
- 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.