SharePoint site groups REST API reference [CRUD] – _api/web/sitegroups

sharepoint-icon-x128

A Brief Introduction


SharePoint is a great collaboration tool from Microsoft. SharePoint can be used as a website and also as a document storage platform. Moreover, SharePoint has very efficient permission management system. Both SharePoint site groups and O365 groups can be used for managing permissions in SharePoint. And more importantly, these SharePoint group permissions can be managed through SharePoint REST API or PowerShell. In this document I have shared the necessary information related to SharePoint site groups REST API resource.

Application of SharePoint site group REST API


Below are some of the possible tasks you can do using SharePoint site groups rest API.

  • Create a site group
  • Update group Properties
  • Get group details
  • Get all site groups details
  • Get users list from a group
  • Add user to a group
  • Remove a user from a group

In this post I have shared implementation examples for all the above SharePoint site group REST API endpoints. Check them below

Please help us grow!

Amazon Links:

Amazon India, Amazon US

Rich Dad & Poor Dad
Know what the Rich Teach Their Kids About Money That the Poor and Middle Class Do Not!

#. Pre-requisite


Below are the prerequisites to work with SharePoint site group REST API

#A little introduction

A SharePoint site group is a resource/object which you can add/use in SharePoint to manage permissions. SP site groups allows to manage permission more efficiently and easily. A basic difference between SharePoint site group and O365 group is that, SharePoint groups do not have any email address associated with them. And thus you can’t send email to those groups.

SharePoint site group have many properties, some of them can be read/updated using REST API endpoints. Below are some basic properties which you should be aware of (important ones are in bold).

PropertyTypeRead/WriteReturned with resourceDescription
AllowMembersEditMembershipBooleanRWYesGets or sets a value that indicates whether the group members can edit membership in the group.
AllowRequestToJoinLeaveBooleanRWYesGets or sets a value that indicates whether to allow users to request membership in the group and request to leave the group.
AutoAcceptRequestToJoinLeaveBooleanRWNoGets or sets a value that indicates whether the request to join or leave the group can be accepted automatically.
CanCurrentUserEditMembershipBooleanRNoGets a value that indicates whether the current user can edit the membership of the group.
CanCurrentUserManageGroupBooleanRNoGets a value that indicates whether the current user can manage the group.
CanCurrentUserViewMembershipBooleanRNoGets a value that indicates whether the current user can view the membership of the group.
DescriptionStringRWYesGets or sets the description of the group.
IdInt32RYesGets a value that specifies the member identifier for the user or group.
LoginNameStringRYesGets the name of the group.
OnlyAllowMembersViewMembershipBooleanRWYesGets or sets a value that indicates whether only group members are allowed to view the membership of the group.
OwnerTitleStringRYesGets the name for the owner of this group.
PrincipalTypeInt32RYesGets a value containing the type of the principal. Represents a bitwise SP.PrincipalType value: None = 0; User = 1; DistributionList = 2; SecurityGroup = 4; SharePointGroup = 8; All = 15.
TitleStringRWYesGets or sets a value that specifies the name of the principal.
UsersSP.UserCollectionRNoGets a collection of user objects that represents all of the users in the group.
SharePoint Site group properties

#. Implementation


#Ex 1: Get a SharePoint site group details [REST API]

The Uri for getting site groups details is
http://<your site>/_api/web/sitegroups

The sitegroups resource Uri above, returns all site groups details for a particular SharePoint site. However if you need to get only one particular group then you can use either filter query or the sitegroups resource methods. Two of the methods for getting a particular group details are

  • GetById – Gets a group detail by Id
  • GetByName – Gets group detail by Name

#Ex 1.1: GetById – SharePoint site groups method [REST API]

To get a group by id, you need to know the id. There are two ways to know the id of a group, they are

  1. Manually – Navigate to people & group settings for a particular site. Then open any group of your choice and the id of the group will be mentioned at the end of the URL of that particular page.
SharePoint REST API for site groups - id
  1. Programmatically – There are many ways to do it, including but not limited to using the sitegroups Uri and then getting the id.

Anyways, once you have the id, you can call the following REST API endpoint using any method of your choice to get site group details. Below is one example.
Below example is shown using POSTMAN web application. If you are not sure how to generate an access token to call the API, please check this document.

Successful REST API call from POSTMAN for site group details
Particular site group resource

To get group details using getbyname method, just pass the group name as a parameter. An example is as follows,
_api/web/sitegroups/getbyname(‘group name’)

That’s all for getting a particular group detail.

#Ex 2: Get All users of group

The getById method only returns the details about the group but does not return the user details. If you need to know the user details then call the users method of the group as below.
As you can see, the return result is an array of user details. This array contains all user details added in that particular group.
Remember the LoginName parameter, this parameter will be used later to add/remove users to/from the group.

site group user details using SharePoint REST API

#Ex 3: Remove/Delete a Group

To delete a SharePoint group you can use any of the following REST API methods, removeById() or removeByLoginName(). An example is below

remove SharePoint group from site using REST API

#Ex 4: Create a group using REST API

To create a group you need to send a POST request to the sitegroups resource of the site with the following body as parameter. You can include other parameters from the above table as well. Just make sure that you are not trying to modify a read-only parameter.

    { 
	'__metadata':{
            'type': 'SP.Group' 
	 }, 
	    'Title':'New Group' 
    }

The above body contains the minimum information you must to pass to create a group. An example request is below

Site group creation request using SharePoint REST API

#Ex 5: Add user to a SharePoint group

To add a user to a group you need to send a POST request with the follow body

{ 
	'__metadata': 
{ 'type': 'SP.User' }, 
	'LoginName':<Proper Login name format> 
}

The login name needs to be in a specific format, depending upon your SharePoint hosting and authentication method. If you see in the previous example #2, the login name parameter is visible. As of now there are three types of LoginName parameter type, they are as below.

SharePoint environmentExample login name format
SharePoint Online, or
SharePoint 2013 on-premises using forms
i:0#.f|membership|user@domain.com
SharePoint 2013 on-premises using Windows claimsi:0#.w|domain\user
SharePoint 2013 on-premises using SAML claimsi:05:t|adfs with roles|user@domain.com

As I am using SharePoint Online, the login name is formatted in the first format type. Now with the above reference use the correct login name format as per your environment and call the REST API endpoint. See the below example as a reference

Add user to a group using SharePoint REST API
Upon successful execution of the API call, you will see 201 HTTP response code

If you are receiving error, i.e. __metadata does not exist, check this post
https://newbietechie.com/the-property-__metadata-does-not-exist-on-type-sp-data/

#Ex 6: Get User using Email or LoginName

One of the common requirements is to check if a user exists in a site or not. With the help of SharePoint REST API endpoints, this can be done very easily. To get user from SharePoint resource you can use the GetByEmail or LoginName endpoint. See the below examples

SharePoint REST API To Get User By Email
Returned result if user exists

Now if the API is called but the user does not exist in the group, then below response will be received (i.e. 404 not found).

User not found in group SharePoint site group REST API reference

As you can see, it returned 404 not found response.

That’s all I have for this document and I hope you are now familiar with SharePoint group REST API resource. If you found this post helpful please share it with others and make sure to support the writer using any of the below options. Thank you!

Please Help us Grow!

I hope you have found this article helpful. If you are happy with the document, please use the below links when you buy something from Amazon to help us grow.

Ways to Help

Amazon Affiliate Links

How this works?

Amazon affiliate program gives a small (%)share of price to the referrers, so feel free to buy anything.
Below are some Amazon affiliate links, if you open amazon application/website using these links and buy something, (it can be one of the below items or anything of your choice) Then Amazon will give us a little percentage(%) of the money you spend on Amazon. To know more check this document.

$350-Best Student laptop
Amazon In, Amazon US

$600-Work laptop
Amazon In, Amazon US

$989– High performance
Amazon In, Amazon US

Headset – $15.99
Amazon In, Amazon US

Lightspeed Mouse – $39
Amazon In, Amazon US

Keyboard – $29
Amazon In, Amazon US

The Psychology of Money
Amazon In, Amazon

Atomic Habits:
Amazon In, Amazon

Find Balance and Purpose in Life
Amazon In, Amazon

$30, Smart Watch for Smart you
Amazon In, Amazon US, Amazon UK

Work comfortably with $110
Amazon In, Amazon US, Amazon UK

Exercise at home
Amazon In, Amazon US, Amazon UK

Thank you
For your Contribution

Leave a Comment