SharePoint REST API Metadata Explorer
On 3 minutesThe sp-rest-explorer
is a wonderful website to explore all the APIs available on SharePoint. You can find it at
https://s-kainet.github.io/sp-rest-explorer
For example, if you browse to web > Alert
, you can see that the Alert
has a method called Add
with signature as _api/web/Alerts/Add(...)/
. It takes as a parameter, alertCreationInformation
which is of type SP.AlertCreationInformation
.
And the SP.AlertCreationInformation
properties as below.
Property Type
AlertFrequency Int32
AlertTemplateName String
AlertTime DateTime
AlertType Int32
AlwaysNotify Boolean
DeliveryChannels Int32
EventType Int32
EventTypeBitmask Int32
Filter String
Properties Collection (SP.KeyValue)
Status Int32
Title String
You can post to the endpoint, _api/web/Alerts/Add
with the payload
{
"parameters":{
"__metadata":{
"type":"SP.AlertCreationInformation"
},
"AlertFrequency":2,
"AlertTemplateName":"SPAlertTemplateType.WebPageLibrary",
"AlertType":2,
"AlwaysNotify":"true",
"DeliveryChannels":1,
"EventType":1,
"Filter":"<Query><And><Or><Eq><FieldRef Name=\"SomeField\"/><Value type=\"string\">Word</Value></Eq><Eq><FieldRef Name=\"SomeField\"/><Value type=\"string\">Excel</Value></Eq></Or><Or><Eq><FieldRef Name=\"SomeSkill\"/><Value type=\"string\">2 - Fortgeschritten</Value></Eq></Or></And></Query>",
"List":"3b80d325-4031-4de5-ae7f-5f6dd5f86b72",
"Title":"My Filtered Notification",
"User":6
}
}
AlertCreationInformation myNewAlert = new AlertCreationInformation();
// myNewAlert.Item = companylibrary.GetItemByUniqueId(alertfolder.UniqueId);
myNewAlert.List = clientContext.Web.Lists.GetByTitle(CompanyType);
myNewAlert.AlertFrequency = AlertFrequency.Immediate;
myNewAlert.AlertTime = DateTime.Now;
myNewAlert.AlertType = AlertType.List;
myNewAlert.AlwaysNotify = true;
myNewAlert.DeliveryChannels = AlertDeliveryChannel.Email;
myNewAlert.EventType = AlertEventType.All;
myNewAlert.Filter = "2";
// 0 = Anything Changes
// 1 = Someone else changes a document
// 2 = Someone else changes a document created by me
// 3 = Someone else changes a document modified by me
myNewAlert.Status = AlertStatus.On;
myNewAlert.Title = "My new alert created at : " + DateTime.Now.ToString();
myNewAlert.User = clientContext.Web.CurrentUser;
var newAlertGuid = clientContext.Web.CurrentUser.Alerts.Add(myNewAlert);
clientContext.ExecuteQuery();
Additional Notes
Headers
Make sure to change the Content-type header as below
Content-Type: "application/json; odata=verbose"
If you receive the error The property '__metadata' does not exist on type xxxx
, make sure you have set the content type above.
Function Endpoint
When you call a function endpoint, the payload needs to have the top attribute parameters.
{
"parameters":{
...
}
}
Example of function endpoint is _api/web/Alerts/Add(...)/
Parameter Type
For every function call, you need to indicate the type of parameter you are passing. This is done by using the __metadata
attribute. For example, to create a view, you need to pass ViewCreationInformation
to the endpoint /_api/Web/Lists/GetByTitle('Listname')/Views/Add
.
{
"parameters":{
"__metadata":{
"type":"SP.ViewCreationInformation"
}
}
}
Collection
Whenever an attribute is specified as a collection, for example the ViewFields
attribute of the ViewCreationInformation
is of type Collection(String)
, it needs to be crafted in a specific format. Below is an example of how you will craft a collection attribute (ViewFields). Notice that you have to specify the attribute type using the __metadata
attribute.
{
"parameters":{
"__metadata":{
"type":"SP.ViewCreationInformation"
},
"ViewFields":{
"__metadata":{
"type":"Collection(Edm.String)"
},
"results":[
"LinkTitle",
"UnitPrice"
]
}
}
}
Other Resources
https://docs.microsoft.com/en-us/previous-versions/office/developer/sharepoint-rest-reference/jj860569(v=office.15)
JavaScript API reference for SharePoint 2013 | Microsoft Docs
@FRIMPONG, I followed above Rest API endpoint with mentioned payload to create new alert for a Site Pages library. i am thrown errors for User & List objects. I passed the values for them properly. But still i get “The property ‘List’ does not exist on type ‘SP.AlertCreationInformation’. Make sure to only use property names that are defined by the type.” I i remove those properties, then i get “Unknown Error”. Post URL : https://mysite.sharepoint.com/sites/sitecoll/subsite/_api/web/Alerts/Add My payload : { “alertCreationInformation”:{ “__metadata”:{ “type”:”SP.AlertCreationInformation” }, “AlertFrequency”:0, “AlertTemplateName”:”SPAlertTemplateType.WebPageLibrary”, “AlertType”:0, “AlwaysNotify”:”true”, “DeliveryChannels”:-1, “EventType”:1, “List”:”6d1136d3-c6e4-47c2-9c19-ee764a23fa9c”, “Title”:”My Filtered Notification”, “User”:10 } } Any guidance to troubleshoot… Read more »
I faced the same issue. Please help
I made a mistake in the payload. I have updated the post. Kindly try and let me know.
I made a mistake in the payload. I have updated the post. Kindly try and let me know. The alertCreationInformation attribute should be parameters and check you content-type header
it doesn’t accept the top level attribute “parameters”
Are you able to show a working example of how to add a new alert using Power Automate (Flow) and the Send an HTTP Request to SharePoint action?
I want to automate as if the following parameters were manually set on the ‘New Alert’ user alerts SharePiont page:-
Alert Title: Urgent News
Send Alert to: (specific site user(s))
Delivery method: E-mail
Change Type: New items are added
Send Alerts for These Changes: Someone changes an item that appears in the following view: (select relevant view from drop-down, e.g. “Urgent News Items”)
When to Send Alerts: Immediately