UserPermission API

In Surpass, a user’s ability to view and interact with different parts of the system depends on their “permissions”. Each part of the system has a unique permission, which acts as a key. Only users with the relevant permission can access a given part of the system. If a user does not have permissions for an area of the system, they will not see it.

Individual permissions can be combined into a profile called a “role”, which can then be given to a user. A role gives a user all of the included permissions. Each role in Surpass has a unique identifier. For information on the unique identifier for each role, read Permission API. Read Creating a new role for information on how to create a custom role.

The UserPermission API resource is used to retrieve, assign, and delete user and permission (role) associations.

This article explains what calls can be made to the Surpass API using the UserPermission resource.

Import this API into your Postman Workspace

Listing user and permission associations

get /api/v2/UserPermission

Send a request to the endpoint to retrieve a list of user and permission (role) associations. 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.

EXAMPLE: The endpoint /api/v2/User?$filter=user/reference eq 'User1' would return all the permissions (roles) assigned to User1.

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/UserPermission?$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/UserPermission?$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/UserPermission?$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 `id`, `user/reference`; `{operator}` is `eq` (equal to); and `{value}` is the string or integer 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.
orderBy	query OPTIONAL	`/api/v2/UserPermission?$orderBy={attribute}`	Determines order of results, where `{attribute}` is `id.`

TIP: Multiple query parameters can be passed in a request at once. filter parameters can be joined using and between attributes. top, skip, and other parameters are joined using &. For example, the endpoint /api/v2/UserPermission?$top=10&$skip=25 would skip the first 25 results and return 10.

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": 1905,
    "top": 10,
    "skip": 0,
    "pageCount": 191,
    "nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/UserPermission?$skip=10",
    "prevPageLink": null,
    "response": [
        {
            "id": 1,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/1"
        },
        {
            "id": 2,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/2"
        },
        {
            "id": 3,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/3"
        },
        {
            "id": 4,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/4"
        },
        {
            "id": 5,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/5"
        },
        {
            "id": 6,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/6"
        },
        {
            "id": 7,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/7"
        },
        {
            "id": 8,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/8"
        },
        {
            "id": 9,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/9"
        },
        {
            "id": 10,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/10"
        }
    ],
    "errors": null
}

Retrieving user and permission association information

get /api/v2/UserPermission/{id}

Send a request to the endpoint to retrieve information for a specific user and permission (role) association using its ID. No request body is required.

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.

path

OPTIONAL

/api/v2/UserPermission/{id}

Returns information for the specified user and permission (role) association, where {id} is the user and permission (role) association’s unique identifier.

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,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/1",
            "user": {
                "id": 1,
                "reference": "User1",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/User/1"
            },
            "permission": {
                "id": 2,
                "assignable": true
            }
        }
    ],
    "errors": null
}

Response schema

The response schema contains a description of every property that can be returned for this endpoint.

count integer

Details how many user and permission (role) associations there are in total. This is null because the information retrieved is for a specific user and permission (role) association.

top integer

Details number of user and permission (role) associations returned in the response. This is null because the information retrieved is for a specific user and permission (role) association.

skip integer

Details how many user and permission (role) associations were skipped to display those in the response. This is null because the information retrieved is for a specific user and permission (role) association.

pageCount integer

Details how many pages of user and permission (role) associations there are. This is null because the information retrieved is for a specific user and permission (role) association.

nextPageLink string

The endpoint to call the next page of user and permission (role) associations. This is null because the information retrieved is for a specific user and permission (role) association.

prevPageLink string

The endpoint to call the previous page of user and permission (role) associations. This is null because the information retrieved is for a specific user and permission (role) association.

response array

Contains the rest of the response.

id integer

The user and permission (role) association’s unique identifier.

href string

The endpoint to call the user and permission (role) association’s information, such as /api/v2/UserPermission/{id} where {id} is the user and permission (role) association’s unique identifier.

user object

The user’s information.

user/id integer

The user’s unique identifier.

user/reference string

The user’s unique reference code.

user/href string

The endpoint to call the user’s information, such as /api/v2/User/{id} where {id} is the user’s unique identifier.

permission object

Contains the permission (role) assigned to the user.

permission/id integer

Contains the unique identifier for the user’s role. For information on the unique identifier for each role, read Permission API.

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.

Assigning a role to a user

post /api/v2/UserPermission

Send a request to the endpoint to assign a role to a user.

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 request

The following requests contain the minimum required request body to assign a role to a user.

{
    "user": {
        "id": 1
    },
    "permission": {
        "id": 2,
        "assignable": true
    }
}

EXAMPLE: In this sample request, the site administrator role is assigned to User 1.

{
    "user": {
        "id": 1
    },
    "centre": {
        "id": 1,
    },
    "permission": {
        "id": 3,
        "assignable": true
    }
}

EXAMPLE: In this sample request, the centre administrator role is assigned to user 1 for centre 1.

{
    "user": {
        "id": 1
    },
    "centre": {
        "id": 1,
    },
    "subject": {
        "id": 1,
    },
    "permission": {
        "id": 5,
        "assignable": true
    }
}

EXAMPLE: In this sample request, the subject owner role is assigned to user 1 for subject 1.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new user and permission (role) association’s details.

{
    "id": 1,
    "href": "https://{your Surpass instance}.surpass.com/api/v2/UserPermission/1",
    "errors": null
}

Deleting a user and permission association

delete /api/v2/UserPermission/{id}

Send a request to the endpoint to delete a specific user and permission (role) association. No request body is required.

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.

path

MANDATORY

/api/v2/UserPermission/{id}

Deletes specified user and permission (role) association, where {id} is the user and permission (role) association’s unique identifier.

Sample response

If successful, the HTTP status code will be 200 and the response body will confirm the user and permission (role) association has been deleted by returning a null id.

{
    "id": null,
    "href": null,
    "errors": 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/UserPermission?$skip={skip}` query parameter, where `{skip}` is a number that should not exceed the total number of responses.
UserPermissionDoesNotExist	49	The specified user and permission (role) association does not exist.
UserPermissionAlreadyExist	50	The specified user and permission (role) association already exists.

UserPermission API

In This Article

Listing user and permission associations

Parameters

Sample response

Response schema

Retrieving user and permission association information

Parameters

Sample response

Response schema

Assigning a role to a user

Parameters

Sample request

Request body schema

Sample response

Deleting a user and permission association

Parameters

Sample response

Error Codes

Further reading

About the site