User API
In Surpass, a “user” is someone who interacts with the system. Users create items, set up and schedule tests, mark scripts, and view reporting analytics. Users are always associated with at least one parent centre.
The User API resource is used to list, retrieve, create, update, and delete users.
This article explains what calls can be made to the Surpass API using the User resource.
Import this API into your Postman Workspace
In This Article
Listing users
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 |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
top |
query OPTIONAL |
/api/v2/User?$top={top} |
Defines number of responses to return when paging a response, where {top} is a number between 1 and 40. |
|
skip |
query OPTIONAL |
/api/v2/User?$skip={skip} |
Defines how many responses to skip when paging a response, where {skip} is a number that should not exceed the total number of responses. |
|
filter |
query OPTIONAL |
/api/v2/User?$filter={filter} {operator} {value} |
Filters results, searching either for an exact match or for the data to contain a defined value. For an exact match: {filter} is one of id, reference, firstName, lastName, ssoExternalId, email, jobTitle, defaultLanguage, retired; {operator} is eq (equal to); and {value} is the string, integer or Boolean the filter query looks for an exact match for in the request. For a greater than query: {filter} is id, {operator} is ge (greater than), and {value} is the integer the filter looks for more than in the request. For a less than query: {filter} is id, {operator} is le (less than), and {value} is the integer the filter looks for less than in the request. For a contains query: {filter} is contains({attribute}, '{value}'), where {attribute} is one of reference, firstName, lastName, ssoExternalId, email, jobTitle; and {value} is the string or integer the filter query looks for the data to contain in the request. |
|
orderBy |
query OPTIONAL |
/api/v2/User?$orderBy={attribute} |
Determines order of results, where {attribute} is one of id, reference, firstName, lastName, ssoExternalId, email, jobTitle, defaultLanguage, dateCreated, expiryDate. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": 100,
"top": 10,
"skip": 0,
"pageCount": 10,
"nextPageLink": "https://{your Surpass instance}.com:443/api/v2/User?$top=10&$skip=10",
"prevPageLink": null,
"response": [
{
"id": 1,
"reference": "User1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/1"
},
{
"id": 2,
"reference": "User2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/2"
},
{
"id": 3,
"reference": "User3",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/3"
},
{
"id": 4,
"reference": "User4",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/4"
},
{
"id": 5,
"reference": "User5",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/5"
},
{
"id": 6,
"reference": "User6",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/6"
},
{
"id": 7,
"reference": "User7",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/7"
},
{
"id": 8,
"reference": "User8",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/8"
},
{
"id": 9,
"reference": "User9",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/9"
},
{
"id": 10,
"reference": "User10",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/10"
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many users there are in total.
top integer
Details number of users returned in the response.
skip integer
Details how many users were skipped to display those in the response.
pageCount integer
Details how many pages of users there are.
nextPageLink string
The endpoint to call the next page of users. If null, the response is the last page of users.
prevPageLink string
The endpoint to call the previous page of users. If null, the response is the first page of users.
response array
Contains the rest of the response.
id integer
The user’s unique identifier.
reference string
The user’s username and unique reference code.
href string
The endpoint to call the user’s information, such as /api/v2/User/{id} where {id} is the user’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving user information
Send a request to the endpoint to retrieve information for a specific user using either their ID or reference. 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 |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path OPTIONAL |
/api/v2/User/{id} |
Returns information for the specified user, where {id} is the user’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/User?reference={reference} |
Returns information for the specified user, where {reference} is the user’s username and unique reference code. |
|
showPermissions |
query OPTIONAL |
/api/v2/User/{id}?showPermissions={Boolean} |
If {Boolean} is true, returns permissions information for the specified user, where {id} is the user’s unique identifier (or reference code). |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": null,
"top": null,
"skip": null,
"pageCount": null,
"nextPageLink": null,
"prevPageLink": null,
"response": [
{
"id": 1,
"reference": "User1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/1",
"firstName": "Stuart",
"lastName": "Fenwick",
"ssoExternalId": null,
"email": "stuart.fenwick@surpass.com",
"jobTitle": "Test Centre Administrator",
"defaultLanguage": "English",
"dateCreated": "2016-04-27T08:07:53.983",
"retired": false,
"expiryDate": "2027-05-21T18:46:31.813"
"userPermissions": [
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/1",
"centre": {
"id": 1,
"reference": "Centre1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/1"
},
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"permission": {
"id": 5,
"assignable": true
}
}
]
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many users there are in total. This is null because the information retrieved is for a specific user.
top integer
Details number of users returned in the response. This is null because the information retrieved is for a specific user.
skip integer
Details how many users were skipped to display those in the response. This is null because the information retrieved is for a specific user.
pageCount integer
Details how many pages of users there are. This is null because the information retrieved is for a specific user.
nextPageLink string
The endpoint to call the next page of users. This is null because the information retrieved is for a specific user.
prevPageLink string
The endpoint to call the previous page of users. This is null because the information retrieved is for a specific user.
response array
Contains the rest of the response.
id integer
The user’s unique identifier.
reference string
The user’s username and unique reference code.
href string
The endpoint to call the user’s information, such as /api/v2/User/{id} where {id} is the user’s unique identifier.
firstName string
The user’s first name.
lastName string
The user’s last name.
ssoExternalId string
The user’s Single Sign-On external ID. For a successful Single Sign-On integration, this must match a NameID attribute in the identity provider (IdP). If null, Single Sign-On is not enabled. Read Single Sign-On for more information.
email string
The user’s email address.
jobTitle string
The user’s job title.
defaultLanguage enumeration
Determines whether the user’s default language is English (UK) (English), English (US) (EnglishUs), Dutch (Dutch), Arabic (Arabic), German (German), Spanish (Spanish), Latin American Spanish (SpanishLatinAmerica), French Canadian (FrenchCanadian), or Welsh (Welsh).
dateCreated string
The date the user was created, in YYYY/MM/DD format.
retired boolean
Determines whether the user is retired. Users have to be retired before they can be deleted.
expiryDate string
The user’s expiry date, in YYYY/MM/DD format. Defaults to 10 years.
userPermissions array
Contains the user’s role(s) (permission).
userPermissions/id integer
The unique identifier of the association between the user and their permission(s).
userPermissions/href string
The endpoint to call the association between the user and their permission(s) information, such as /api/v2/UserPermission/{id} where {id} is the association between the user and their permission(s) unique identifier.
userPermissions/centre object
Contains the information of the centre the user’s role (permission) is for.
userPermissions/centre/id integer
The unique identifier of the centre.
userPermissions/centre/reference string
The unique reference code of the centre.
userPermissions/subject object
Contains the information of the subject the role (permission) is for.
userPermissions/subject/id integer
The unique identifier of the subject.
userPermissions/subject/reference string
The unique reference code of the subject.
userPermissions/permission object
Contains the user’s role.
userPermissions/permission/id integer
Contains the unique identifier for the user’s role. For information on the unique identifier for each role, read Permission API.
userPermissions/permission/assignable boolean
Determines whether the user can assign the role to other users.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a user
Send a request to the endpoint to create a user.
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 |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
Sample requests
The following requests contain the minimum required request body to create a user.
{
"reference": "User1",
"firstName": "Stuart",
"lastName": "Fenwick",
"email": "stuart.fenwick@surpass.com",
"userPermissions": [
{
"permission": {
"id": 2,
"assignable": true
},
"isSecureClient": false
}
]
}{
"reference": "User2",
"firstName": "Kathrin",
"lastName": "Wilcox",
"email": "kathrin.wilcox@surpass.com",
"userPermissions": [
{
"centre": {
"id": 1,
"reference": "Centre1"
},
"permission": {
"id": 3,
"assignable": true
},
"isSecureClient": false
}
]
}{
"reference": "User3",
"firstName": "Nigella",
"lastName": "Schulz",
"email": "nigella.schulz@surpass.com",
"userPermissions": [
{
"centre": {
"id": 1,
"reference": "Centre1"
},
"subject": {
"id": 1,
"reference": "Subject1"
},
"permission": {
"id": 5,
"assignable": true
},
"isSecureClient": false
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
reference string mandatory
The user’s username and unique reference code.
firstName string mandatory
The user’s first name.
lastName string mandatory
The user’s last name.
ssoExternalId string optional
The user’s Single Sign-On external ID. For a successful Single Sign-On integration, this must match a NameID attribute in the identity provider (IdP). Read Single Sign-On for more information.
email string mandatory
The user’s email address.
jobTitle string optional
The user’s job title.
defaultLanguage enumeration optional
Determines whether the user’s default language is English (UK) (English), English (US) (EnglishUs), Dutch (Dutch), Arabic (Arabic), German (German), Spanish (Spanish), Latin American Spanish (SpanishLatinAmerica), French Canadian (FrenchCanadian), or Welsh (Welsh). Defaults to English (UK) (English) if omitted.
retired boolean optional
Determines whether the user is retired. Users have to be retired before they can be deleted.
expiryDate string optional
The user’s expiry date, in YYYY/MM/DD format. Defaults to 10 years if omitted.
userPermissions array mandatory
Contains the user’s role(s) (permission). Only permission is required to create a site-level role. Pass a centre in the same array as permission to assign a centre-level role for the specified centre. Pass a subject and its centre in the same array to assign a subject-level role for the specified subject.
userPermissions/centre object
Contains the information of the centre the user’s role (permission) is for.
userPermissions/centre/id integer
The unique identifier of the centre.
userPermissions/centre/reference string
The unique reference code of the centre.
userPermissions/subject object
Contains the information of the subject the user’s role (permission) is for.
userPermissions/subject/id integer
The unique identifier of the subject.
userPermissions/subject/reference string
The unique reference code of the subject.
userPermissions/permission object mandatory
Contains the user’s role.
userPermissions/permission/id integer
Contains the unique identifier for the user’s role.
userPermissions/permission/assignable boolean
Determines whether the user can assign the role to other users. Defaults to false if omitted.
isSecureClient boolean mandatory
Determines whether the user has the SecureClient administrator role.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new user’s details.
{
"id": 1,
"reference": "User1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/1",
"errors": null,
"serverTimeZone": null
}Updating a user
Send a request to the endpoint to update a specific user.
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 |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path OPTIONAL |
/api/v2/User/{id} |
Updates specified user, where {id} is the user’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/User?reference={reference} |
Updates specified user, where {reference} is the user’s username and unique reference code. |
Sample request
At least one property must be updated in the request. The following request contains the minimum required request body to update a user. Refer to the request body schema for all properties that can be updated.
{
"firstName": "Iqbal"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
firstName string
The user’s first name.
lastName string
The user’s last name.
ssoExternalId string
The user’s Single Sign-On external ID. For a successful Single Sign-On integration, this must match a NameID attribute in the identity provider (IdP). Read Single Sign-On for more information.
email string
The user’s email address.
jobTitle string
The user’s job title.
defaultLanguage enumeration
Determines whether the user’s default language is English (UK) (English), English (US) (EnglishUs), Dutch (Dutch), Arabic (Arabic), German (German), Spanish (Spanish), Latin American Spanish (SpanishLatinAmerica), French Canadian (FrenchCanadian), or Welsh (Welsh).
retired boolean
Determines whether the user is retired. Users have to be retired before they can be deleted.
expiryDate string
The user’s expiry date, in YYYY/MM/DD format.
userPermissions array
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated user’s details.
{
"id": 1,
"reference": "User1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/1",
"errors": null,
"serverTimeZone": null
}Deleting a user
Send a request to the endpoint to delete a specific user. 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 |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path OPTIONAL |
/api/v2/User/{id} |
Deletes specified user, where {id} is the user’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/User?reference={reference} |
Deletes specified user, where {reference} is the user’s username and unique reference code. |
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the user has been deleted by returning a null id.
{
"id": null,
"href": null,
"errors": null,
"serverTimeZone": null
}Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Name |
Code |
Description |
|---|---|---|
|
InternalServer |
1 |
Internal server error. |
|
Unauthorized |
3 |
The request has been sent by an unauthorised user. |
|
IncorrectFieldFormat |
4 |
A field in the request has not been completed in the correct format. |
|
InaccessibleOperation |
5 |
The request has been sent by a user with invalid permissions. |
|
InaccessibleData |
6 |
The request has been sent by a user with invalid permissions. |
|
MissingBody |
7 |
There is an issue with the request body. |
|
InvalidReference |
11 |
The unique reference code used in the request is invalid. |
|
InvalidInputParameters |
15 |
There is an issue with the path or query parameters. |
|
InvalidId |
16 |
The ID number used in the request is invalid. |
|
InvalidODataOperation |
19 |
There is an issue with the query parameters. |
|
BadRequest |
20 |
There is an issue with the /api/v2/User?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
|
UserDoesNotExist |
40 |
The specified user does not exist. |
|
FailedToDeleteUser |
41 |
There is an issue with deleting a user. |
|
FailedToCreateUser |
42 |
There is an issue with creating a user. |
|
CannotCreateNotAssignableSiteAdministrator |
67 |
There is an issue with creating a user with an assignable site administrator role. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: