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:
userGroupId if you are adding a user group to a collection.
userGroupId if you are updating user group permissions of a collection.
userGroupId if you are removing a user group from a collection.
userGroupId if you want to share a credential with a user group.
userGroupId if you want to remove a user group from a credential.
userGroupId if you want to add a user group to a data connection.
userGroupId if you want to remove a user group from a data connection.
Postman Request Examples
POST /v3/usergroups
DELETE /v3/usergroups/{userGroupId}/users/{userId}
To know more about Postman requests, visit the How to Use Postman help page.