Users, groups, and roles REST API reference

Learn about the REST API for the User, Group, RoleAssigment, RoleDefinition, UserCustomAction and related resources.

Applies to: apps for SharePoint | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

In this article
About the request examples in this article
Explore the SharePoint 2013 users and groups REST syntax
Group resource
GroupCollection resource
RoleAssignment resource
RoleAssignmentCollection resource
RoleDefinition resource
RoleDefinitionCollection resource
RoleDefinitionBindingCollection resource
User resource
UserCollection resource
UserCustomAction resource
UserCustomActionCollection resource
Additional resources

About the request examples in this article

The request examples in this article assume that you’re using the cross-domain library (SP.RequestExecutor.js) to make cross-domain requests, so they use SP.AppContextSite in the endpoint URI. See How to: Access SharePoint 2013 data from apps using the cross-domain library for more information.

Before you use a request example, do the following:

• Change <app web url>, <host web url>, and other placeholder data such as any IDs, names, or paths of SharePoint entities.

• If you’re not using the cross-domain library, include an X-RequestDigest header to send the form digest value in all POST requests and a content-length header for POST requests that send data in the request body.

• If you're not making cross-domain requests, remove SP.AppContextSite(@target) and ?@target='<host web url>' from the endpoint URI.

• If you’re using OAuth, include an Authorization header ("Authorization": "Bearer " + <access token>) to send the OAuth access token.

• Remove the line breaks from the url and body property values in the request examples. Line breaks are added to the examples to make them easier to read.

• If you want the server to return responses in Atom format, remove the "accept": "application/json; odata=verbose" header.

See Additional resources for links to more information about using the cross-domain library, OAuth, and the SharePoint REST service. See How REST requests differ by environment and Properties used in REST requests for information about request formats.

Tip

The SharePoint Online REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. For details and links to code samples, see Make batch requests with the REST APIs. This option is not yet supported for on-premise SharePoint.

Explore the SharePoint 2013 users and groups REST syntax

Visually explore the SharePoint 2013 users and groups REST syntax. Explore other SharePoint REST syntax diagrams: Files and folders | Lists and list items Download the combined PDF of all the SharePoint REST syntax diagrams.

Group resource

Represents a collection of users in a SharePoint site. A group is a type of SP.Principal.

Endpoint URI  |  Properties  |  OData representation

Endpoint URI

http://<site url>/_api/web/sitegroups(<group id>)

Supported HTTP methods

GET  |  POST  |  MERGE  |  PUT

Request examples

GET request example: Get a group

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

You can also get a group by LoginName. See the GetByName method.

MERGE request example: Change a group

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Group' }, 'Description':'New description of the group' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

To add a user to a group, add the user to the group's user collection, as shown in the UserCollection request examples. To remove a user from a group, use the RemoveById method or RemoveByLoginName method from the UserCollection resource.

PUT request example: Replace a group

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(30)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Group' }, 'Title':'Training',
    'Description':'Description of new group', 'AllowMembersEditMembership':'false',
    'AllowRequestToJoinLeave':'false', 'AutoAcceptRequestToJoinLeave':'false',
    'OnlyAllowMembersViewMembership':'true', 'RequestToJoinLeaveEmailSetting':'true' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "PUT"
  },
  success: successHandler,
  error: errorHandler
});

Use the RemoveById method or the RemoveByLoginName method to delete a group. To create a group, send a POST request to the GroupCollection resource. See GroupCollection request examples for an example.

Group properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
AllowMembersEditMembership	Boolean	RW	Yes	Gets or sets a value that indicates whether the group members can edit membership in the group.
AllowRequestToJoinLeave	Boolean	RW	Yes	Gets or sets a value that indicates whether to allow users to request membership in the group and request to leave the group.
AutoAcceptRequestToJoinLeave	Boolean	RW	No	Gets or sets a value that indicates whether the request to join or leave the group can be accepted automatically.
CanCurrentUserEditMembership	Boolean	R	No	Gets a value that indicates whether the current user can edit the membership of the group.
CanCurrentUserManageGroup	Boolean	R	No	Gets a value that indicates whether the current user can manage the group.
CanCurrentUserViewMembership	Boolean	R	No	Gets a value that indicates whether the current user can view the membership of the group.
Description	String	RW	Yes	Gets or sets the description of the group.
Id	Int32	R	Yes	Gets a value that specifies the member identifier for the user or group.
IsHiddenInUI	Boolean	R	Yes	Gets a value that indicates whether this member should be hidden in the UI.
LoginName	String	R	Yes	Gets the name of the group.
OnlyAllowMembersViewMembership	Boolean	RW	Yes	Gets or sets a value that indicates whether only group members are allowed to view the membership of the group.
Owner	SP.Principal	RW	No	Gets or sets the owner of the group which can be a user or another group assigned permissions to control security.
OwnerTitle	String	R	Yes	Gets the name for the owner of this group.
RequestToJoinLeaveEmailSetting	String	RW	Yes	Gets or sets the email address to which the requests of the membership are sent.
PrincipalType	Int32	R	Yes	Gets 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.
Title	String	RW	Yes	Gets or sets a value that specifies the name of the principal.
Users	SP.UserCollection	R	No	Gets a collection of user objects that represents all of the users in the group.

OData representation

The following example represents a Group resource in JSON format.

    {"d":{
      "__metadata":{,
        "id":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
        "uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
       "type":"SP.Group"
      },
      "Owner":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Owner"}},
      "Users":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Users"}},
      "Id":5,
      "IsHiddenInUI":false,
      "LoginName":"Members",
      "Title":"Members",
      "PrincipalType":8,
      "AllowMembersEditMembership":false,
      "AllowRequestToJoinLeave":false,
      "AutoAcceptRequestToJoinLeave":false,
      "Description":"Use this group to grant people contribute permissions to the SharePoint site: ",
      "OnlyAllowMembersViewMembership":false,
      "OwnerTitle":"Owners",
      "RequestToJoinLeaveEmailSetting":""
    }}

GroupCollection resource

Represents a collection of Group resources.

Endpoint URI  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/sitegroups

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get the groups at the root site

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a group

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

You can also get a group by LoginName. See the GetByName method.

POST request example: Create a group

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Group' }, 'Title':'New Group' }",
  headers: { "content-type": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

See Group request examples for examples of how to change a group.

GroupCollection methods

GetById
GetByName
RemoveById
RemoveByLoginName

GetById method

Returns a group from the collection based on the member ID of the group.

Endpoint	/getbyid(<group id>)
HTTP method	GET
Parameters	Type: Int32 The ID of the group to get.
Response	Type: SP.Group The specified group.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /getbyid(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or you can just specify the group ID on the GroupCollection resource. Example: …/_api/web/sitegroups(5)

GetByName method

Returns a cross-site group from the collection based on the name of the group.

Endpoint	/getbyname('<group name>')
HTTP method	GET
Parameters	Type: String The name of the group. The group name is specified in its LoginName property.
Response	Type: SP.Group The specified group.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /getbyname('content site owners')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

RemoveById method

Removes the group with the specified member ID from the collection.

Endpoint	/removebyid(<group id>)
HTTP method	POST
Parameters	Type: Int32 The ID of the group to remove.
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /removebyid(17)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

RemoveByLoginName method

Removes the cross-site group with the specified name from the collection.

Endpoint	/removebyloginname('<group name>')
HTTP method	POST
Parameters	Type: String The name of the group to remove. The group name is specified in its LoginName property.
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /removebyloginname('training')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a GroupCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"https://<site url>/_api/Web/SiteGroups/GetById(7)",
          "uri":"https://<site url>/_api/Web/SiteGroups/GetById(7)",
          "type":"SP.Group"
        },
        "Owner":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(7)/Owner"}},
        "Users":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(7)/Users"}},
        "Id":7,
        "IsHiddenInUI":false,
        "LoginName":"Excel Services Viewers",
        "Title":"Excel Services Viewers",
        "PrincipalType":8,
        "AllowMembersEditMembership":false,
        "AllowRequestToJoinLeave":false,
        "AutoAcceptRequestToJoinLeave":false,
        "Description":"Members of this group can view pages, list items, and documents. If the document has a server rendering available, they can only view the document using the server rendering.",
        "OnlyAllowMembersViewMembership":true,
        "OwnerTitle":"Owners",
        "RequestToJoinLeaveEmailSetting":null
        },{
        "__metadata":{
          "id":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
          "uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
          "type":"SP.Group"
        },
        "Owner":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Owner"}},
        "Users":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Users"}},
        "Id":5,
        "IsHiddenInUI":false,
        "LoginName":"Members",
        "Title":"Members",
        "PrincipalType":8,
        "AllowMembersEditMembership":false,
        "AllowRequestToJoinLeave":false,
        "AutoAcceptRequestToJoinLeave":false,
        "Description":"Use this group to grant people contribute permissions to the SharePoint site: ",
        "OnlyAllowMembersViewMembership":false,
        "OwnerTitle":"Owners",
        "RequestToJoinLeaveEmailSetting":""
        },
        ...
      }]
    }}

RoleAssignment resource

Defines the securable object role assignments for a user or group on the Web site, list, or list item.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/roleassignments(<principal id>)

Supported HTTP methods

GET  |  POST  |  DELETE

Request examples

GET request example: Get a role assignment

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

DELETE request example: Delete a role assignment

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

Or you can use the RemoveRoleAssignment method to remove a role assignment. To create a role assignment, use the AddRoleAssignment method.

RoleAssignment properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /roleassignments(3)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
Member	SP.Principal	R	No	Gets the user or group that corresponds to the Role Assignment.
PrincipalId	Int32	R	Yes	The unique identifier of the role assignment.
RoleDefinitionBindings	SP.RoleDefinitionCollection	R	No	Gets the collection of role definition bindings for the role assignment.

RoleAssignment methods

DeleteObject

DeleteObject method

The recommended way to delete a role assignment is to use the RemoveRoleAssignment method or to send a DELETE request to the RoleAssignment resource endpoint, as shown in RoleAssignment request examples.

OData representation

The following example represents a RoleAssignment resource in JSON format.

    {"d":{
      "__metadata":{,
        "id":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
        "uri":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
        "type":"SP.RoleAssignment"
      },
      "Member":{"__deferred":{"uri":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/Member"}},
      "RoleDefinitionBindings":{"__deferred":{"uri":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/RoleDefinitionBindings"}},
      "PrincipalId":3
    }}

RoleAssignmentCollection resource

Represents a collection of RoleAssignment resources.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/roleassignments

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get a role assignment

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Use the AddRoleAssignment method to create a role assignment. To delete a role assignment, use the RemoveRoleAssignment method or send a DELETE request to the RoleAssignment resource endpoint, as shown in RoleAssignment request examples.

RoleAssignmentCollection properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)/groups
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
Groups	SP.GroupCollection	R	No	Gets the groups that directly belong to the access control list (ACL) for this securable object.

RoleAssignmentCollection methods

AddRoleAssignment
GetByPrincipalId
RemoveRoleAssignment

AddRoleAssignment method

Adds a new role assignment with the specified principal and role definitions to the collection.

Endpoint	/addroleassignment(principalid, roledefid)
Parameters	principalid Type: Int32 The ID of the user or group to assign permissions to. roledefid Type: Int32 The ID of the role definition that defines the permissions to assign. See RoleDefinitionCollection request examples for an example of how to create a role definition.
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments
    /addroleassignment(principalid=21, roledefid=1073741827)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

To use this method on an object that inherits permissions, you first have to call the BreakRoleInheritance method on the object. See How to: Set custom permissions on a list by using the REST interface.

GetByPrincipalId method

Gets the role assignment associated with the specified principal ID from the collection.

Endpoint	/getbyprincipalid(<prinicipal id>)
Parameters	Type: Int32 The PrincipalId of the role assignment to get.
HTTP method	GET
Response	Type: SP.RoleAssignment The specified role assignment.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments
    /getbyprincipalid(3)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or you can just specify the principal ID of the role assignment on the RoleAssignmentCollection resource. Example: …/_api/web/roleassignments(3)

RemoveRoleAssignment method

Removes the role assignment with the specified principal and role definition from the collection.

Endpoint	/removeroleassignment(principalid, roledefid)
Parameters	principalid Type: Int32 The ID of the user or group in the role assignment. roledefid Type: Int32 The ID of the role definition in the role assignment.
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments
    /removeroleassignment(principalid=21, roledefid=1073741827)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a RoleAssignmentCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)",
          "uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)",
          "type":"SP.RoleAssignment"
        },
        "Member":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)/Member"}},
        "RoleDefinitionBindings":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)/RoleDefinitionBindings"}},
        "PrincipalId":1
        },{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
          "uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
          "type":"SP.RoleAssignment"
        },
        "Member":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/Member"}},
        "RoleDefinitionBindings":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/RoleDefinitionBindings"}},
        "PrincipalId":3
        },{
        ...
      }]
    }}

RoleDefinition resource

Defines a single role definition, including a name, description, and set of rights.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/roledefinitions(<role definition id>)

Supported HTTP methods

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Request examples

GET request example: Get a role definition

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741829)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MERGE request example: Change a role definition

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741928)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.RoleDefinition' }, 'BasePermissions':
    { '__metadata': { 'type': 'SP.BasePermissions' }, 'High': '48' } }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

PUT request example: Replace a role definition

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741928)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.RoleDefinition' }, 'BasePermissions':
    { '__metadata': { 'type': 'SP.BasePermissions' }, 'High': '48' }, 
   'Description': 'New description', 'Name': 'New name', 'Order': 170 }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "PUT"
  },
  success: successHandler,
  error: errorHandler
});

DELETE request example: Delete a role definition

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741928)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

See RoleDefinitionCollection request examples for an example that shows how to create a role definition.

RoleDefinition properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /roledefinitions(1073741829)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
BasePermissions	SP.BasePermissions	RW	Yes	Gets or sets a value that specifies the base permissions for the role definition.
Description	String	RW	Yes	Gets or sets a value that specifies the description of the role definition.
Hidden	Boolean	R	Yes	Gets a value that specifies whether the role definition is displayed.
Id	Int32	R	Yes	Gets a value that specifies the Id of the role definition.
Name	String	RW	Yes	Gets or sets a value that specifies the role definition name.
Order	Int32	RW	Yes	Gets or sets a value that specifies the order position of the object in the site collection Permission Levels page.
RoleTypeKind	Int32	R	Yes	Gets a value that specifies the type of the role definition. Represents an SP.RoleType value. See RoleType in the .NET client object model reference for a list of role type values.

RoleDefinition methods

DeleteObject

DeleteObject method

The recommended way to delete a role definition is to send a DELETE request to the RoleDefinition resource endpoint, as shown in RoleDefinition request examples.

OData representation

The following example represents a RoleDefinition resource in JSON format.

    {"d":{
      "__metadata":{,
        "id":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
        "uri":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
        "type":"SP.RoleDefinition"
      },
      "BasePermissions":{"__metadata":{"type":"SP.BasePermissions"}, "High":"2147483647", "Low":"4294967295"},
      "Description":"Has full control.",
      "Hidden":false,
      "Id":1073741829,
      "Name":"Full Control",
      "Order":1,
      "RoleTypeKind":5
    }}

RoleDefinitionCollection resource

Represents the collection of RoleDefinition resources.

Endpoint URI  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/roledefinitions

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get a role definition

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741829)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST request example: Create a role definition

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.RoleDefinition' }, 'BasePermissions': 
    { '__metadata': { 'type': 'SP.BasePermissions' }, 'High': '176' , 'Low': '138612801' }, 
    'Description': 'New description', 'Name': 'New role', 'Order': 180 }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

See RoleDefinition request examples for examples of how to change or delete a role definition.

RoleDefinitionCollection methods

GetById
GetByName
GetByType

GetById method

Gets the role definition with the specified ID from the collection.

Endpoint	/getbyid(<role definition id>)
Parameters	Type: Int32 The ID of the role definition.
HTTP method	GET
Response	Type: SP.RoleDefinition The specified role definition.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    /getbyid(1073741829)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or you can just specify the role definition ID on the RoleDefinitionCollection resource. Example: …/_api/web/roledefinitions(1073741829)

GetByName method

Gets the role definition with the specified name.

Endpoint	/getbyname('<role definition name>')
Parameters	Type: String The name of the role definition.
HTTP method	GET
Response	Type: SP.RoleDefinition The specified role definition.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    /getbyname('contribute')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetByType method

Gets the role definition with the specified role type.

Endpoint	/getbytype(<role definition type>)
Parameters	Type: Int32 The RoleTypeKind of the role definition. See RoleType in the .NET client object model reference for a list of role type values.
HTTP method	GET
Response	Type: SP.RoleDefinition The specified role definition.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    /getbytype(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a RoleDefinitionCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "uri":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "type":"SP.RoleDefinition"
        },{
        "__metadata":{
          "type":"SP.BasePermissions"},
          "High":"2147483647",
          "Low":"4294967295"
        },
        "Description":"Has full control.",
        "Hidden":false,
        "Id":1073741829,
        "Name":"Full Control",
        "Order":1,
        "RoleTypeKind":5
        },{
        ...
      }]
    }}

RoleDefinitionBindingCollection resource

Defines the role definitions that are bound to a role assignment object.

Endpoint URI  |  OData representation

Endpoint URI

http://<site url>/_api/web/roleassignments(<role assignment id>)/roledefinitionbindings

Supported HTTP methods

GET

Request examples

GET request example: Get the role definition bindings for a role assignment

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(7)
    /roledefinitionbindings
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler});

To create a role assignment, which binds a principal (user or group) to a role definition, use the AddRoleAssignment method. To delete a role assignment, use the RemoveRoleAssignment method or send a DELETE request to the RoleAssignment resource endpoint, as shown in RoleAssignment request examples.

OData representation

The following example represents a RoleDefinitionBindingCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "uri":"http://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "type":"SP.RoleDefinition"
        },{
        "__metadata":{
          "type":"SP.BasePermissions"},
          "High":"2147483647",
          "Low":"4294967295"
        },
        "Description":"Has full control.",
        "Hidden":false,
        "Id":1073741829,
        "Name":"Full Control",
        "Order":1,
        "RoleTypeKind":5
        },{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleDefinitions(1073741827)",
          "uri":"http://<site url>/_api/Web/RoleDefinitions(1073741827)",
          "type":"SP.RoleDefinition"
        },{
        "__metadata":{
          "type":"SP.BasePermissions"},
          "High":"432",
          "Low":"1011028719"
        },
        "Description":"Can view, add, update, and delete list items and documents.",
        "Hidden":false,
        "Id":1073741827,
        "Name":"Contribute",
        "Order":64,
        "RoleTypeKind":3
      }]
    }}

User resource

Represents a user in Microsoft SharePoint Foundation. A user is a type of SP.Principal.

Endpoint URI  |  Properties  |  OData representation

Endpoint URI

http://<site url>/_api/web/sitegroups(<group id>)/users(@v)?@v='<login name>'
http://<site url>/_api/web/siteusers(@v)?@v='<login name>'

The format of the login name for users depends on your SharePoint environment, as described in Table 1:

Table 1. Login name formats

SharePoint environment	Example login name format	How to pass the login name by using an alias in the query string
SharePoint Online, or SharePoint 2013 on-premises using forms	i:0#.f|membership|user@domain.com	…/users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
SharePoint 2013 on-premises using Windows claims	i:0#.w|domain\user	…/users(@v)?@v='i%3A0%23.w%7Cdomain\user'
SharePoint 2013 on-premises using SAML claims	i:05:t|adfs with roles|user@domain.com	…/users(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'

Note

The format of the login name in the Security Assertion Markup Language (SAML)-based claims authentication example assumes that the identity claim is configured to use email address or user principal name. SAML claims authentication cannot be used in SharePoint-hosted apps.

Supported HTTP methods

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Request examples

GET request example: Get a user from a site by login name

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/siteusers(@v)
    ?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a user from a site by id

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/getuserbyid(16)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a user from a group by login name

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

You can also get a user from a group by email address or by ID. See the GetByEmail method and the GetById method.

MERGE request example: Change a user

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.User' }, 'Title':'New display name' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

PUT request example: Replace a user

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.User' }, 'Email':'user2@domain.com', 'IsSiteAdmin':false, 'Title':'User 2' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "PUT"
  },
  success: successHandler,
  error: errorHandler});

See UserCollection request examples for an example of how to add a user to a group.

DELETE request example: Remove a user from a group

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users/getbyid(18)
    &@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

To remove a user by using the DELETE method on the User resource, you have to get the user from the user collection by using the GetById method or GetByEmail method. Or, you can just use the RemoveById method or RemoveByLoginName method from the UserCollection resource.

User properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)/<property name>?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
Email	String	RW	Yes	Gets or sets the email address of the user.
Groups	SP.GroupCollection	R	No	Gets the collection of groups of which the user is a member.
Id	Int32	R	Yes	Gets a value that specifies the member identifier for the user or group.
IsHiddenInUI	Boolean	R	Yes	Gets a value that indicates whether this member should be hidden in the UI.
IsSiteAdmin	Boolean	RW	Yes	Gets or sets a Boolean value that specifies whether the user is a site collection administrator.
LoginName	String	R	Yes	Gets the login name of the user.
PrincipalType	Int32	R	Yes	Gets 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.
Title	String	RW	Yes	Gets or sets a value that specifies the name of the principal.
UserId	SP.UserIdInfo	R	Yes	Gets the information of the user that contains the user's name identifier and the issuer of the user's name identifier.

OData representation

The following example represents a User resource in JSON format.

    {"d":{
      "__metadata":{,
        "id":"http://<site url>/_api/Web/GetUserById(16)",
        "uri":"http://<site url>/_api/Web/GetUserById(16)",
        "type":"SP.User"
      },
      "Groups":{"__deferred":{"uri":"http://<site url>/_api/Web/GetUserById(16)/Groups"}},
      "Id":16,
      "IsHiddenInUI":false,
      "LoginName":"i:0#.w|domain\\user",
      "Title":"User Display Name",
      "PrincipalType":1,
      "Email":"user@company.com",
      "IsSiteAdmin":false,
      "UserId":{"__metadata":{"type":"SP.UserIdInfo"}, "NameId":"s-0-0-00-000000-0000000000-0000000000-000000", "NameIdIssuer":"issuer id" }
    }}

UserCollection resource

Represents a collection of User resources.

Endpoint URI  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/siteusers
http://<site url>/_api/web/sitegroups(<group id>)/users

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get a user by login name

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/siteusers(@v)
    ?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get the users in a group

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(7)/users
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST request example: Add a user to a group

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(7)/users
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.User' }, 'LoginName':'i:0#.w|domain\\user' }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

UserCollection methods

GetByEmail
GetById
GetByLoginName
RemoveById
RemoveByLoginName

GetByEmail method

Gets the user with the specified email address.

Endpoint	/getbyemail('<email address>')
Parameters	Type: String The email of the user to get.
HTTP method	GET
Response	Type: SP.User The specified user.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /getbyemail('user@domain.com'),
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetById method

Gets the user with the specified member identifier (ID).

Endpoint	/getbyid(<user id>)
Parameters	Type: Int32 The ID of the user to get.
HTTP method	GET
Response	Type: SP.User The specified user.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /getbyid(23)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetByLoginName method

Gets the user with the specified login name.

Endpoint	/getbyloginname(@v)?@v='<login name>'
Parameters	Type: String The login name of the user to get, passed as an alias in the query string. For example:   SharePoint Online or on-premises using forms: …/getbyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'   On-premises using Windows claims: …/getbyloginname(@v)?@v='i%3A0%23.w%7Cdomain\user'   On-premises using SAML claims: …/getbyloginname(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'
HTTP method	GET
Response	Type: SP.User The specified user.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /getbyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or you can just specify the login name on the UserCollection resource. Example: …/_api/web/siteusers(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'

RemoveById method

Removes the user with the specified ID.

Endpoint	/removebyid(<user id>)
Parameters	Type: Int32 The ID of the user to remove.
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /removebyid(24)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

RemoveByLoginName method

Removes the user with the specified login name.

Endpoint	/removebyloginname(@v)?@v='<login name>'
Parameters	Type: String The login name of the user to remove, passed as an alias in the query string. For example:   SharePoint Online or on-premises using forms: …/removebyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'   On-premises using Windows claims: …/removebyloginname(@v)?@v='i%3A0%23.w%7Cdomain\user'   On-premises using SAML claims: …/removebyloginname(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /removebyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a UserCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/GetUserById(16)",
          "uri":"http://<site url>/_api/Web/GetUserById(16)",
          "type":"SP.User"
        },
        "Groups":{"__deferred":{"uri":"http://<site url>/_api/Web/GetUserById(16)/Groups"}},
        "Id":16,
        "IsHiddenInUI":false,
        "LoginName":"i:0#.w|domain\\user1",
        "Title":" User1 Display Name ",
        "PrincipalType":1,
        "Email":"user1@company.com",
        "IsSiteAdmin":false,{
        "__metadata":{
          "type":"SP.UserIdInfo"},
          "NameId":"s-0-0-00-000000-0000000000-0000000000-000000",
          "NameIdIssuer":"issuer id"
        }},{
        "__metadata":{
          "id":"http://<site url>/_api/Web/GetUserById(21)",
          "uri":"http://<site url>/_api/Web/GetUserById(21)",
          "type":"SP.User"},
        "Groups":{"__deferred":{"uri":"http://<site url>/_api/Web/GetUserById(21)/Groups"}},
        "Id":21,
        "IsHiddenInUI":false,
        "LoginName":"i:0#.w|domain\\user2",
        "Title":" User2 Display Name ",
        "PrincipalType":1,
        "Email":"user2@company.com",
        "IsSiteAdmin":false,{
        "__metadata":{
          "type":"SP.UserIdInfo"},
          "NameId":"s-0-0-00-000000-0000000000-0000000000-000001",
          "NameIdIssuer":"issuer id"
        }
      }]
    }}

UserCustomAction resource

Represents a custom action associated with a SharePoint list, Web site, or subsite.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/usercustomactions('<user custom action id>')

Supported HTTP methods

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Request examples

GET request example: Get a custom action

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MERGE request example: Change a custom action

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.UserCustomAction' }, 'Title':'New title' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

DELETE request example: Delete a custom action

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

See UserCustomActionCollection request examples for an example that shows how to create a custom action.

UserCustomAction properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
CommandUIExtension	String	RW	Yes	Gets or sets a value that specifies an implementation specific XML fragment that determines user interface properties of the custom action.
Description	String	RW	Yes	Gets or sets the description of the custom action.
Group	String	RW	Yes	Gets or sets a value that specifies an implementation-specific value that determines the position of the custom action in the page.
Id	GUID	R	Yes	Gets a value that specifies the identifier of the custom action.
ImageUrl	String	RW	Yes	Gets or sets the URL of the image associated with the custom action.
Location	String	RW	Yes	Gets or sets the location of the custom action.
Name	String	RW	Yes	Gets or sets the name of the custom action.
RegistrationId	String	RW	Yes	Gets or sets the value that specifies the identifier of the object associated with the custom action.
RegistrationType	Int32	RW	Yes	Gets or sets the value that specifies the type of object associated with the custom action. Represents an SP.UserCustomActionRegistrationType value: None = 0; List = 1; ContentType = 2; ProgId = 3; FileType = 4.
Rights	SP.BasePermissions	RW	Yes	Gets or sets the value that specifies the permissions needed for the custom action.
Scope	Boolean	R	Yes	Gets a value that specifies the scope of the custom action.
ScriptBlock	String	RW	Yes	Gets or sets the value that specifies the ECMAScript to be executed when the custom action is performed.
ScriptSrc	String	RW	Yes	Gets or sets a value that specifies the URI of a file which contains the ECMAScript to execute on the page.
Sequence	Int32	RW	Yes	Gets or sets the value that specifies an implementation-specific value that determines the order of the custom action that appears on the page.
Title	String	RW	Yes	Gets or sets the display title of the custom action.
Url	String	RW	Yes	Gets or sets the URL, URI, or ECMAScript (JScript, JavaScript) function associated with the action.
VersionOfUserCustomAction	String	R	Yes	Gets a value that specifies an implementation specific version identifier.

UserCustomAction methods

DeleteObject

DeleteObject method

The recommended way to delete a file is to send a DELETE request to the UserCustomAction resource endpoint, as shown in UserCustomAction request examples.

OData representation

The following example represents a UserCustomAction resource in JSON format.

    {"d":{
      "__metadata":{,
        "id":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
        "uri":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
        "type":"SP.UserCustomAction"
      },
      "CommandUIExtension":null,
      "Description":"Opens the Shared Documents page",
      "Group":"SiteActions",
      "Id":"98bffbf9-c911-4c59-a807-cac99647f889",
      "ImageUrl":null,
      "Location":"Microsoft.SharePoint.StandardMenu",
      "Name":null,
      "RegistrationId":null,
      "RegistrationType":0,
      "Rights":{"__metadata":{"type":"SP.BasePermissions"}, "High":"0", "Low":"0"},
      "Scope":3,
      "ScriptBlock":null,
      "ScriptSrc":null,
      "Sequence":101,
      "Title":"Open Shared Docs",
      "Url":"http://<site url>/Shared%20Documents/Forms/AllItems.aspx",
      "VersionOfUserCustomAction":"15.0.1.0"
    }}

UserCustomActionCollection resource

Represents a collection of UserCustomAction resources.

Endpoint URI  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/usercustomactions

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get all custom actions on a site

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a custom action

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST request example: Create a custom action

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.UserCustomAction' }, 'Location':'Microsoft.SharePoint.StandardMenu',
    'Group':'SiteActions', 'Sequence':'101', 'Title':'Open Shared Docs',
    'Description':'Opens the Shared Documents page', 'Url':'~site/Shared%20Documents/Forms/AllItems.aspx' }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

See UserCustomAction request examples for examples of how to change or delete a custom action.

UserCustomActionCollection methods

Clear
GetById

Clear method

Deletes all custom actions in the collection.

Endpoint	/clear
Parameters	None
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    /clear
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

GetById method

Returns the custom action with the specified identifier.

Endpoint	/getbyid(<user custom action id>)
Parameters	Type: Guid The ID of the user custom action to get.
HTTP method	GET
Response	Type: SP.UserCustomAction The specified user custom action.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    /getbyid('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or you can just specify the action ID on the UserCustomActionCollection resource. Example: …/_api/web/usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')

OData representation

The following example represents a UserCustomActionCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/UserCustomActions(guid'c38d9d91-c5e8-4fbd-9040-52b03024d2a3')",
          "uri":"http://<site url>/_api/Web/UserCustomActions(guid'c38d9d91-c5e8-4fbd-9040-52b03024d2a3')",
          "type":"SP.UserCustomAction"
        },
        "CommandUIExtension":null,
        "Description":"Opens the Site Contents page",
        "Group":"SiteActions",
        "Id":"c38d9d91-c5e8-4fbd-9040-52b03024d2a3",
        "ImageUrl":null,
        "Location":"Microsoft.SharePoint.StandardMenu",
        "Name":"{c38d9d91-c5e8-4fbd-9040-52b03024d2a3}",
        "RegistrationId":null,
        "RegistrationType":0,{
        "__metadata":{ "type":"SP.BasePermissions"}, "High":"0", "Low":"0" },
        "Scope":3,
        "ScriptBlock":null,
        "ScriptSrc":null,
        "Sequence":102,
        "Title":"Open Site Contents",
        "Url":"~site/_layouts/15/viewlsts.aspx",
        "VersionOfUserCustomAction":"15.0.1.0"},{
        "__metadata":{
          "id":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
          "uri":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
          "type":"SP.UserCustomAction"},
        "CommandUIExtension":null,
        "Description":"Opens the Shared Documents page",
        "Group":"SiteActions",
        "Id":"98bffbf9-c911-4c59-a807-cac99647f889",
        "ImageUrl":null,
        "Location":"Microsoft.SharePoint.StandardMenu",
        "Name":"{98bffbf9-c911-4c59-a807-cac99647f889}",
        "RegistrationId":null,
        "RegistrationType":0,{
        "__metadata":{ "type":"SP.BasePermissions"}, "High":"0", "Low":"0" },
        "Scope":3,
        "ScriptBlock":null,
        "ScriptSrc":null,
        "Sequence":101,
        "Title":"Open Shared Docs",
        "Url":"http://<site url>/Shared%20Documents/Forms/AllItems.aspx",
        "VersionOfUserCustomAction":"15.0.1.0"
      }]
    }}

Additional resources

• Working with folders and files with REST

• How to: Complete basic operations using SharePoint 2013 REST endpoints

• How to: Access SharePoint 2013 data from apps using the cross-domain library

• OAuth authentication and authorization flow for cloud-hosted apps

• Use OData query operations in SharePoint REST requests

• REST API reference and samples

• Get started with the SharePoint 2013 REST service