Skip to content

Retrieving Users By Role

Description

All users have different roles assigned to them, those can be default system roles assigned by the system and also custom roles. By invoking this operation you can find users by a custom role; the result of this operation is an array of user objects found by a specific role.  This operation works only with custom roles, otherwise an error message will be returned in response.

Method

GET

Endpoint URL

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

https://xxxx.backendless.app/api/users/role/<roleName>

where:

Argument                Description
<roleName> is a string name of a particular role.

Request Headers

Content-Type: application/json

where:

Argument                Description
Content-Type must be set to application/json. This header is mandatory.

Request Body

None.

Response Body

An array containing multiple user objects.

Example

The example below retrieves all users associated with the user role TrialUser. 

curl --location --request GET 'https://xxxx.backendless.app/api/users/role/TrialUser

where:

Argument                Description
TrialUser Is a custom role assigned to users that must be returned in the response.

Codeless Reference

user_service_codeless_get_users_by_role

where:

Argument                Description
role name A string name of a particular role.
load roles Optional parameter. When set to true, this operation returns a list containing all security roles associated with every returned user.
relations Optional parameter. Sets an array of related columns names. Objects from the related columns are included into the response.
properties Optional parameter. Sets the names of the properties which values to include into the response.
relations depth Optional parameter. Sets the number of "levels" in the hierarchy of related objects to include into the response.
page size Sets the page size - which is the number of objects to return in the response. Maximum value is 100.
page offset Optional parameter. Sets the offset - an index in the server-side storage from where the data objects should be retrieved.

Returns a list containing multiple user objects.

Consider the following records in the Users data table:

user_service_example_get_users_by_role_new_1

Suppose the Alice and Charlie records both have the "TrialUser" role assigned to them; the example below retrieves users by role "TrialUser".

user_service_example_get_users_by_role_new_2

The result of this operation is a list containing two objects, representing the Alice and Charlie records in the data table. These records have the "TrialUser" role assigned to them:

user_service_example_get_users_by_role_new_3

For more details about the related data tables refer to the Relations Overview topic.

Sometimes you may want to retrieve additional data from the related table using the relations property. This argument expects a list containing column(s) that reference records in the related data table.

Consider the following records in the Users data table.  Note that the data column is related to the UserData table where additional user information is stored. You need to use relation values  stored in the data column in your requests to retrieve additional information from the UserData table.


user_service_codeless_example_get_users_by_role_1

Consider the UserData table below, it is the custom data table where additional information is stored. Every single record in this data table is related(linked) to another record stored in the Users data table presented above.

user_service_codeless_example_get_users_by_role_4

In the context of this example the email column represents the identity. The UserData table contains information stored in the age, address and phone columns.

The example below obtains users from the Users data table that have the "TrialUser" role assigned to them. Pay attention how additional user information is obtained from the custom table called UserData: the relations parameter expects the column name that has relations to the UserData table; In this case the name of the column that has relations is data.

To limit the number of columns returned in the response, you must pass a list to the properties parameter, containing column names that you want to have in the response (e.g. email, name).

user_service_codeless_example_get_users_by_role_2

The output will look as shown below after the Codeless logic runs:
user_service_codeless_example_get_users_by_role_3

As you can see the operation has returned two user objects containing user information.  In the "userData" property you can find an object containing additional(related) user information returned from the UserData table.