Skip to main content

User Group Endpoints

User Group Endpoints and Parameters

To learn more about the objects relations and how to use them in the API, go to the Object Relations section.

For more information about custom groups, visit the User and Group Management help page.

Create a New User Group

To create a new userGroup record, use the POST {baseURL}/v3/usergroups endpoint.

Parameters

To create a new user group, specify the contract parameter:

  • contract (body): Required. Specify the parameters for a user group:

    • name (string): Required. Enter a user group name.

    • role (string): Required. Enter a role for this user group. Select from these options: NoAccess, Viewer, Member, Artisan, Curator, and Evaluated. The default (Evaluated) role is evaluated at runtime. For more information about roles and permissions, visit the User Roles and Permissions page.

Request Example: cURL

curl --location --request POST 'http://localhost/webapi/v3/usergroups' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --data-urlencode 'name=Accounting' \ --data-urlencode 'role=Artisan'

Add a User to a User Group

To add one or more users to a user group, use the POST {baseURL}/v3/usergroups/{id}/users endpoint.

Parameters

To add users to a user group, specify the following parameters:

  • id (string): Required. Enter the ID of the user group to which you want to add users.

  • userIds (body): Required. Enter the user IDs you want to add to this user group.

Retrieve All Custom User Groups

To search for users, use the GET {baseURL}/v3/usergroups endpoint. Use various parameters as a filter for searching the users.

Note

Only Custom User Groups will be retrieved. No Active Directory Groups will be returned.

Parameters

No parameters required.

Request Example: cURL

curl --location --request GET 'http://localhost/webapi/v3/usergroups' \ --header 'Authorization: Bearer BearerTokenGoesHere'

Search for a Specific User Group

To retrieve information about a specific user group, use the GET {baseURL}/v3/usergroups/{id} endpoint.

Note

Only works for Custom User Groups. Active Directory Groups cannot be retrieved from this endpoint.

Parameters

  • id (string): Required. Enter a user group ID to retrieve information about this user group.

Request Example: cURL

curl --location --request GET 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069' \ --header 'Authorization: Bearer BearerTokenGoesHere'

Update a User Group

To update an existing user group’s name and role, use the PUT {baseURL}/v3/usergroups/{id} endpoint.

Parameters

  • id (string): Required. Enter a user group ID to get this user group updated.

  • contract (body): Required. To update a user group, the contract parameter is required. Specify the following:

    • name (string): Required. Enter a user group name.

    • role (string): Required. You can select from these options: NoAccess, Viewer, Member, Artisan, Curator, and Evaluated. For more information about roles and permissions, visit the User Roles and Permissions page.

Request Example: cURL

curl --location --request PUT 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --data-urlencode 'name=Marketing' \ --data-urlencode 'role=Artisan'

Remove a User from a User Group

To remove a specific user from a user group, use the DELETE {baseURL}/v3/usergroups/{userGroupId}/users/{userId} endpoint.

Note

If the user is not a part of the group, then an OK response will be returned.

Parameters

  • userGroupId (string): Required. Enter the ID of the user group from which you want to remove the user.

  • userId (string): Required. Enter the user ID you want to remove from the user group.

Request Example: cURL

curl --location --request DELETE 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069/users/61d564361d6d5da7ad461a32' \ --header 'Authorization: Bearer BearerTokenGoesHere'

Delete a User Group

To delete a specific user group from the system, use the DELETE {baseURL}/v3/usergroups/{id} endpoint.

Note

The ‘400 Bad Request’ error message is returned if the user group is not empty and the forceDelete query parameter is false.

Parameters

  • id (string): Required. Enter the user group ID you want to delete.

  • forceDelete (boolean): Optional. If set to true, the user group will be deleted even if this user group contains users.

Request Example: cURL

curl --location --request DELETE 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069?forceDelete=true' \ --header 'Authorization: Bearer BearerTokenGoesHere'

Objects Relations

If you are creating a user group, you can use created objects as follows:

Object created: "id" (for example, "id": "619158e57e607d0011ac3009")

You can use it as:

Postman Request Examples

POST /v3/usergroups

Example of a POST request in Postman.

DELETE /v3/usergroups/{userGroupId}/users/{userId}

Example of a DELETE request in Postman.

To know more about Postman requests, visit the How to Use Postman help page.