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.
To create a new userGroup record, use the POST {baseURL}/v3/usergroups
endpoint.
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.
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'
To add one or more users to a user group, use the POST {baseURL}/v3/usergroups/{id}/users
endpoint.
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.
To be added.
To search for users, use the GET {baseURL}/v3/usergroups
endpoint. Use various parameters as a filter for searching the users.
Nota
Only Custom User Groups will be retrieved. No Active Directory Groups will be returned.
No parameters required.
curl --location --request GET 'http://localhost/webapi/v3/usergroups' \ --header 'Authorization: Bearer BearerTokenGoesHere'
To retrieve information about a specific user group, use the GET {baseURL}/v3/usergroups/{id}
endpoint.
Nota
Only works for Custom User Groups. Active Directory Groups cannot be retrieved from this endpoint.
id (string): Required. Enter a user group ID to retrieve information about this user group.
curl --location --request GET 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069' \ --header 'Authorization: Bearer BearerTokenGoesHere'
To update an existing user group’s name and role, use the PUT {baseURL}/v3/usergroups/{id}
endpoint.
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.
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'
To remove a specific user from a user group, use the DELETE {baseURL}/v3/usergroups/{userGroupId}/users/{userId}
endpoint.
Nota
If the user is not a part of the group, then an OK response will be returned.
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.
curl --location --request DELETE 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069/users/61d564361d6d5da7ad461a32' \ --header 'Authorization: Bearer BearerTokenGoesHere'
To delete a specific user group from the system, use the DELETE {baseURL}/v3/usergroups/{id}
endpoint.
Nota
The ‘400 Bad Request’ error message is returned if the user group is not empty and the forceDelete query parameter is false.
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.
curl --location --request DELETE 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069?forceDelete=true' \ --header 'Authorization: Bearer BearerTokenGoesHere'
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.
POST /v3/usergroups
DELETE /v3/usergroups/{userGroupId}/users/{userId}
To know more about Postman requests, visit the How to Use Postman help page.