Working with lists and list items with REST
Tip
The SharePoint Online (and on-premises SharePoint 2016 and later) 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.
Prerequisites
This topic assumes that you're already familiar with the topics Get to know the SharePoint REST service and Complete basic operations using SharePoint REST endpoints. It doesn't provide code snippets.
Retrieving lists and list properties with REST
The following example shows how to retrieve a specific list if you know its GUID.
GET https://{site_url}/_api/web/lists(guid'{list_guid}')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Note
If you want the response in JSON, use application/json;odata=verbose in the Accept header.
If you want the response in Atom format, use application/atom+xml in the Accept header.
The following example shows how to retrieve a specific list if you know its title.
GET https://{site_url}/_api/web/lists/GetByTitle('List Title')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
The following XML shows an example of the list properties that are returned when you request the XML content type.
<content type="application/xml">
<m:properties>
<d:AllowContentTypes m:type="Edm.Boolean">true</d:AllowContentTypes>
<d:BaseTemplate m:type="Edm.Int32">100</d:BaseTemplate>
<d:BaseType m:type="Edm.Int32">0</d:BaseType>
<d:ContentTypesEnabled m:type="Edm.Boolean">false</d:ContentTypesEnabled>
<d:Created m:type="Edm.DateTime">2012-06-26T23:15:58Z</d:Created>
<d:DefaultContentApprovalWorkflowId m:type="Edm.Guid">00000000-0000-0000-0000-000000000000</d:DefaultContentApprovalWorkflowId>
<d:Description>A list created by Project Based Retention used to store Project Policy Items.</d:Description>
<d:Direction>none</d:Direction>
<d:DocumentTemplateUrl m:null="true" />
<d:DraftVersionVisibility m:type="Edm.Int32">0</d:DraftVersionVisibility>
<d:EnableAttachments m:type="Edm.Boolean">true</d:EnableAttachments>
<d:EnableFolderCreation m:type="Edm.Boolean">false</d:EnableFolderCreation>
<d:EnableMinorVersions m:type="Edm.Boolean">false</d:EnableMinorVersions>
<d:EnableModeration m:type="Edm.Boolean">false</d:EnableModeration>
<d:EnableVersioning m:type="Edm.Boolean">false</d:EnableVersioning>
<d:EntityTypeName>ProjectPolicyItemList</d:EntityTypeName>
<d:ForceCheckout m:type="Edm.Boolean">false</d:ForceCheckout>
<d:HasExternalDataSource m:type="Edm.Boolean">false</d:HasExternalDataSource>
<d:Hidden m:type="Edm.Boolean">true</d:Hidden>
<d:Id m:type="Edm.Guid">74de3ff3-029c-42f9-bd2a-1e9463def69d</d:Id>
<d:ImageUrl>/_layouts/15/images/itgen.gif</d:ImageUrl>
<d:IrmEnabled m:type="Edm.Boolean">false</d:IrmEnabled>
<d:IrmExpire m:type="Edm.Boolean">false</d:IrmExpire>
<d:IrmReject m:type="Edm.Boolean">false</d:IrmReject>
<d:IsApplicationList m:type="Edm.Boolean">false</d:IsApplicationList>
<d:IsCatalog m:type="Edm.Boolean">false</d:IsCatalog>
<d:IsPrivate m:type="Edm.Boolean">false</d:IsPrivate>
<d:ItemCount m:type="Edm.Int32">0</d:ItemCount>
<d:LastItemDeletedDate m:type="Edm.DateTime">2012-06-26T23:15:58Z</d:LastItemDeletedDate>
<d:LastItemModifiedDate m:type="Edm.DateTime">2012-06-26T23:15:59Z</d:LastItemModifiedDate>
<d:ListItemEntityTypeFullName>SP.Data.ProjectPolicyItemListItem</d:ListItemEntityTypeFullName>
<d:MultipleDataList m:type="Edm.Boolean">false</d:MultipleDataList>
<d:NoCrawl m:type="Edm.Boolean">true</d:NoCrawl>
<d:ParentWebUrl>/</d:ParentWebUrl>
<d:ServerTemplateCanCreateFolders m:type="Edm.Boolean">true</d:ServerTemplateCanCreateFolders>
<d:TemplateFeatureId m:type="Edm.Guid">00bfea71-de22-43b2-a848-c05709900100</d:TemplateFeatureId>
<d:Title>Project Policy Item List</d:Title>
</m:properties>
</content>
Note
The ListItemEntityTypeFullName property (SP.Data.ProjectPolicyItemListItem in the previous example) is especially important if you want to create and update list items. This value must be passed as the type property in the metadata that you pass in the body of the HTTP request whenever you create and update list items.
Working with lists by using REST
The following example shows how to create a list.
POST https://{site_url}/_api/web/lists
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
{
"__metadata": {
"type": "SP.List"
},
"AllowContentTypes": true,
"BaseTemplate": 100,
"ContentTypesEnabled": true,
"Description": "My list description",
"Title": "Test"
}
The following example shows how to update a list by using the MERGE method.
POST https://{site_url}/_api/web/lists(guid'{list_guid}')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
If-Match: "{etag or *}"
X-HTTP-Method: "MERGE"
X-RequestDigest: "{form_digest_value}"
{
"__metadata": {
"type": "SP.List"
},
"Title": "New title"
}
The following example shows how to create a custom field for a list.
POST https://{site_url}/_api/web/lists(guid'{list_guid}')/Fields
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
{
"__metadata": {
"type": "SP.Field"
},
"Title": "field title",
"FieldTypeKind": FieldType value,
"Required": "true/false",
"EnforceUniqueValues": "true/false",
"StaticName": "field name"
}
The following example shows how to delete a list.
POST https://{site_url}/_api/web/lists(guid'{list_guid}')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"
X-RequestDigest: "{form_digest_value}"
Lookup column changes
When referring to a lookup column inside a list using REST API, use the display name of the lookup column instead of the internal name.
GET https://{site_url}/_api/web/lists/getbytitle('ListName')/Items?&$filter=LookupColumnId eq 1
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Working with list items by using REST
Retrieve all list items
The following example shows how to retrieve all of a list's items.
Note
- The OData
$skipquery parameter doesn't work when querying list items. In many situations, you can use the $skiptoken option instead. - By default, this will return the first 100 items. More information on controlling the number of items, paging, etc. see the documentation on OData Query operations
GET https://{site_url}/_api/web/lists/GetByTitle('Test')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Retrieve specific list item
The following example shows how to retrieve a specific list item.
GET https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id})
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
The following XML shows an example of the list item properties that are returned when you request the XML content type.
<content type="application/xml">
<m:properties>
<d:FileSystemObjectType m:type="Edm.Int32">0</d:FileSystemObjectType>
<d:Id m:type="Edm.Int32">1</d:Id>
<d:ID m:type="Edm.Int32">1</d:ID>
<d:ContentTypeId>0x010049564F321A0F0543BA8C6303316C8C0F</d:ContentTypeId>
<d:Title>an item</d:Title>
<d:Modified m:type="Edm.DateTime">2012-07-24T22:47:26Z</d:Modified>
<d:Created m:type="Edm.DateTime">2012-07-24T22:47:26Z</d:Created>
<d:AuthorId m:type="Edm.Int32">11</d:AuthorId>
<d:EditorId m:type="Edm.Int32">11</d:EditorId>
<d:OData__UIVersionString>1.0</d:OData__UIVersionString>
<d:Attachments m:type="Edm.Boolean">false</d:Attachments>
<d:GUID m:type="Edm.Guid">eb6850c5-9a30-4636-b282-234eda8b1057</d:GUID>
</m:properties>
</content>
Retrieve items as a stream
Retrieves information about the list and its data. Using this API you can retrieve list items in case they use complex fields such as lookups or managed metadata.
POST https://{site_url}/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json;odata=nometadata"
{
"parameters": {
"AddRequiredFields": "true",
"DatesInUtc": "true",
"RenderOptions": 17
}
}
RenderListDataAsStream URI parameters
Following properties can be added as query string parameters to manipulate the returned data.
| Property | Description | Type | Example |
|---|---|---|---|
CascDelWarnMessage |
Specifies if a message should be displayed if there's a cascade deletion warning | number | 1 |
DrillDown |
Specifies that some groups in a grouped view are expanded. Used with GroupString. |
string | |
GroupString |
Group identifier used for drill-down feature. | string | |
HasOverrideSelectCommand |
Used to ensure that certain fields are present for proper functioning of the SharePoint ListView control. | string | |
Field |
Specifies a special field that should be included. | string | |
FieldInternalName |
Used to identify a field when a list has an external data source. Also used when filtering on a custom field. | string | |
Filter |
Specifies whether the requested view should have a filter applied. | string | |
FilterData |
Data specified by a particular filter. | string | |
FilterData1 |
Data specified by a particular filter. | string | |
FilterData2 |
Data specified by a particular filter. | string | |
FilterData3 |
Data specified by a particular filter. | string | |
FilterData4 |
Data specified by a particular filter. | string | |
FilterData5 |
Data specified by a particular filter. | string | |
FilterData6 |
Data specified by a particular filter. | string | |
FilterData7 |
Data specified by a particular filter. | string | |
FilterData8 |
Data specified by a particular filter. | string | |
FilterData9 |
Data specified by a particular filter. | string | |
FilterData10 |
Data specified by a particular filter. | string | |
FilterField |
A filter field name for a specific filter that is applied to the view. | string | |
FilterField1 |
A filter field name for a specific filter that is applied to the view. | string | ID |
FilterField2 |
A filter field name for a specific filter that is applied to the view. | string | ID |
FilterField3 |
A filter field name for a specific filter that is applied to the view. | string | ID |
FilterField4 |
A filter field name for a specific filter that is applied to the view. | string | ID |
FilterField5 |
A filter field name for a specific filter that is applied to the view. | string | ID |
FilterField6 |
A filter field name for a specific filter that is applied to the view. | string | ID |
FilterField7 |
A filter field name for a specific filter that is applied to the view. | string | ID |
FilterField8 |
A filter field name for a specific filter that is applied to the view. | string | ID |
FilterField9 |
A filter field name for a specific filter that is applied to the view. | string | ID |
FilterField10 |
A filter field name for a specific filter that is applied to the view. | string | ID |
FilterFields |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterFields1 |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterFields2 |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterFields3 |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterFields4 |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterFields5 |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterFields6 |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterFields7 |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterFields8 |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterFields9 |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterFields10 |
Specifies multiple fields that are being filtered on for a multiplier filter. | string | |
FilterValue |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | |
FilterValue1 |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | 1 |
FilterValue2 |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | 1 |
FilterValue3 |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | 1 |
FilterValue4 |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | 1 |
FilterValue5 |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | 1 |
FilterValue6 |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | 1 |
FilterValue7 |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | 1 |
FilterValue8 |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | 1 |
FilterValue9 |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | 1 |
FilterValue10 |
The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | 1 |
FilterValues |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterValues1 |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterValues2 |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterValues3 |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterValues4 |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterValues5 |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterValues6 |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterValues7 |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterValues8 |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterValues9 |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterValues10 |
Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth. | string | |
FilterLookupId |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterLookupId1 |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterLookupId2 |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterLookupId3 |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterLookupId4 |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterLookupId5 |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterLookupId6 |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterLookupId7 |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterLookupId8 |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterLookupId9 |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterLookupId10 |
Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on. | string | |
FilterOnly |
string | ||
FilterOp |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
FilterOp1 |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
FilterOp2 |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
FilterOp3 |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
FilterOp4 |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
FilterOp5 |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
FilterOp6 |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
FilterOp7 |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
FilterOp8 |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
FilterOp9 |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
FilterOp10 |
Filter operator. Used when filtering with other operators than Eq (Geq, Leq etc.) |
string | Geq |
ID |
The item id of the item whose information is being sought. | number | |
InplaceSearchQuery |
Search term for a full list search. | string | |
InplaceFullListSearch |
A boolean that specifies whether there's a full list search. | string | |
IsCSR |
Whether this view is a client side rendered view. | string | |
CustomAction |
string | ||
IsGroupRender |
Used to set the IsGroupRender property of the SPView. | string | |
IsRibbon |
string | ||
IsXslView |
Whether this view is an xslt list view. | string | |
List |
string | ||
ListId |
string | ||
ListViewPageUrl |
string | ||
OverrideScope |
Used to override a scope on the rendered view: SPView.Scope | string | |
OverrideSelectCommand |
Used to make sure that certain fields are present in the query regardless of whether they're explicitly included in the view. | string | |
PageFirstRow |
Paging information about the first row that is requested. Used for paging list views. | string | |
PageLastRow |
Paging information about the last row that is requested. Used for paging list views. | string | |
RootFolder |
The folder that the view is displaying. | string | |
SortField |
A field that the view should be sorted on. | string | ID |
SortField1 |
A field that the view should be sorted on. | string | ID |
SortField2 |
A field that the view should be sorted on. | string | ID |
SortField3 |
A field that the view should be sorted on. | string | ID |
SortField4 |
A field that the view should be sorted on. | string | ID |
SortField5 |
A field that the view should be sorted on. | string | ID |
SortField6 |
A field that the view should be sorted on. | string | ID |
SortField7 |
A field that the view should be sorted on. | string | ID |
SortField8 |
A field that the view should be sorted on. | string | ID |
SortField9 |
A field that the view should be sorted on. | string | ID |
SortField10 |
A field that the view should be sorted on. | string | ID |
SortFields |
Specifies the name of the first field to sort by | string | |
SortFieldValues |
Specifies the name of the first field to sort by | string | |
SortDir |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
SortDir1 |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
SortDir2 |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
SortDir3 |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
SortDir4 |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
SortDir5 |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
SortDir6 |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
SortDir7 |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
SortDir8 |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
SortDir9 |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
SortDir10 |
The sort direction of an ad hoc sort that is being applied to the view. | string | Desc |
View |
Specifies the base view that will be used to render the list. | GUID | 3d13559e-3071-5000-76b8-8f1ca6b835f0 |
ViewPath |
Specifies the path of the view that will be used to render the list. If ViewId is given, then the ViewId will be used and this parameter will be ignored. |
string | |
ViewCount |
When multiple list views are on a page, this identifies one of them. | string | |
ViewId |
Specifies the base view that will be used to render the list. ad-hoc parameters will be applied on top of this view. If both ViewXml and BaseViewId are given, then the ViewXml will be used and the ad-hoc parameters will be ignored. |
string | |
WebPartId |
The id of the list view web part that is showing this view. | string |
RenderListDataAsStream body parameter properties
| Property | Description | Type | Example |
|---|---|---|---|
AddRequiredFields |
Specifies if required fields should be returned or not | bool | true |
AllowMultipleValueFilterForTaxonomyFields |
Specifies if multi value filtering is allowed for taxonomy fields or not | bool | true |
DatesInUtc |
Specifies if we return DateTime field in UTC or local time. | bool | true |
ExpandGroups |
Specifies if the grouping should be expanded or not. | bool | true |
FirstGroupOnly |
Specifies if only the first group should be returned or not (regardless of view schema). | bool | true |
FolderServerRelativeUrl |
Specifies the url to the folder from which to return items. | string | /sites/team-a/lists/Orders/Europe |
ImageFieldsToTryRewriteToCdnUrls |
Comma-separated list of field names whose values should be rewritten to CDN URLs | string | ArticleImage,SecondaryImage |
OverrideViewXml |
Specifies the override XML to be combined with the View CAML. Applies only to the Query/Where part of the View CAML. |
string | <Query><Where><Gt><FieldRef Name=\"OrderCount\" /><Value Type=\"Number\">3</Value></Gt></Where></Query> |
Paging |
Specifies the paging information. | string | |
RenderOptions |
Specifies the type of output to return. | SPRenderListDataOptions | See the next section for possible values. You can specify multiple values by adding their values together |
ReplaceGroup |
Specifies if the grouping should be replaced or not to deal with GroupBy throttling. | bool | true |
ViewXml |
Specifies the CAML view XML. | string |
SPRenderListDataOptions options
| Label | Description | Value |
|---|---|---|
None |
Return default output | 0 |
ContextInfo |
Return list context information | 1 |
ListData |
Return list data (same as None) |
2 |
ListSchema |
Return list schema | 4 |
MenuView |
Return HTML for the list menu | 8 |
ListContentType |
Returns information about list content types. Must be combined with the ContextInfo flag |
16 |
FileSystemItemId |
The returned list will have a FileSystemItemId field on each item if possible. Must be combined with the ListData flag |
32 |
ClientFormSchema |
Returns the client form schema to add and edit items | 64 |
QuickLaunch |
Returns QuickLaunch navigation nodes | 128 |
Spotlight |
Returns Spotlight rendering information | 256 |
Visualization |
Returns Visualization rendering information | 512 |
ViewMetadata |
Returns view XML and other information about the current view | 1024 |
DisableAutoHyperlink |
Prevents AutoHyperlink from being run on text fields in this query | 2048 |
EnableMediaTAUrls |
Enables URLs pointing to Media TA service, such as .thumbnailUrl, .videoManifestUrl, .pdfConversionUrls |
4096 |
ParentInfo |
Returns parent folder information | 8192 |
PageContextInfo |
Returns page context info for the current list being rendered | 16384 |
ClientSideComponentManifest |
Return client-side component manifest information associated with the list (reserved for future use) | 32768 |
Examples
Retrieve item with specific ID
POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27&FilterField1=ID&FilterValue1=1
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
...
Sort items descending by ID
POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27&SortField=ID&SortDir=Desc
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
...
Retrieve items from the specified folder
POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FOrders%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json"
{
"parameters": {
"FolderServerRelativeUrl": "/sites/team-a/lists/Orders/Europe"
}
}
Retrieve list schema
POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json"
{
"parameters": {
"RenderOptions": 4
}
}
Retrieve information about list content types
POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json"
{
"parameters": {
"RenderOptions": 17
}
}
Create list item
The following example shows how to create a list item.
Note
To do this operation, you must know the ListItemEntityTypeFullName property of the list and pass that as the value of type in the HTTP request body. Following is a sample rest call to get the ListItemEntityTypeFullName
GET https://{site_url}/_api/web/lists/GetByTitle('Test')?$select=ListItemEntityTypeFullName
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json;odata=verbose"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
{
"__metadata": {
"type": "SP.Data.TestListItem"
},
"Title": "Test"
}
Create list item in a folder
The following example shows how to create a list item in a folder.
POST https://{site_url}/_api/web/lists/GetByTitle('Test')/AddValidateUpdateItemUsingPath
Authorization: "Bearer " + accessToken
Accept "application/json;odata=nometadata"
Content-Type "application/json;odata=nometadata"
X-RequestDigest "The appropriate digest for current site"
{
"listItemCreateInfo": {
"FolderPath": {
"DecodedUrl": "https://{site_url}/lists/Test/Folder/SubFolder"
},
"UnderlyingObjectType": 0
},
"formValues": [
{
"FieldName": "Title",
"FieldValue": "Item"
}
],
"bNewDocumentUpdate": false
}
Request property details
| Property | Description |
|---|---|
listItemCreateInfo |
Information about the list and folder where the item should be created |
listItemCreateInfo.FolderPath.DecodedUrl |
Absolute URL of the folder where the item should be created |
listItemCreateInfo.UnderlyingObjectType |
Type of item to create. For more information, see FileSystemObjectType |
formValues |
Array of field names and values to set on the newly created item |
bNewDocumentUpdate |
Set to false to create a list item |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK | Boolean | Success |
{
"value": [
{
"ErrorMessage": null,
"FieldName": "Title",
"FieldValue": "Item",
"HasException": false,
"ItemId": 0
},
{
"ErrorMessage": null,
"FieldName": "Id",
"FieldValue": "1",
"HasException": false,
"ItemId": 0
}
]
}
The value property contains the list of properties that have been set when creating the list item.
Update list item
The following example shows how to update a list item.
Note
To do this operation, you must know the ListItemEntityTypeFullName property of the list and pass that as the value of type in the HTTP request body.
POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id})
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
If-Match: "{etag or *}"
X-HTTP-Method: "MERGE"
X-RequestDigest: "{form_digest_value}"
{
"__metadata": {
"type": "SP.Data.TestListItem"
},
"Title": "TestUpdated"
}
Delete list item
The following example shows how to delete a list item.
POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id})
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"
Using ETag values to determine document and list item versioning
The SharePoint REST service, which follows the OData standard, uses Header ETags of SharePoint lists and list items. To check on an item's version when you perform a PUT, MERGE, or DELETE request, specify an ETag in the If-Match HTTP request header.
If the ETag you specify in your request doesn't match the ETag of the document or list item on the server, the REST service returns a 412 exception, per the OData specification.
- To force an overwrite of the item regardless of version, set the ETag value to "*".
- If you do not specify an ETag, SharePoint overwrites the item regardless of version.
Within SharePoint, ETags apply only to SharePoint lists and list items.
See also
- Get to know the SharePoint REST service
- SharePoint-Add-in-REST-OData-BasicDataOperations
- SharePoint: Perform basic data access operations on files and folders by using REST
- Secure data access and client object models for SharePoint Add-ins
- Work with external data in SharePoint
- OData resources
- Develop SharePoint Add-ins