Lists and list items REST API reference

SharePoint 2013

Learn about lists, list items, views, and other list-related resources and endpoints in the REST API.

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 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 REST service list and list item syntax

Visually explore the SharePoint 2013 lists and list items REST syntax.

Explore other SharePoint REST syntax diagrams:

Files and folders | Users and groups

Download the combined PDF of all the SharePoint REST syntax diagrams.

Note Note

The OData $skip query option does not work when querying items of a particular list. It does work when querying the lists endpoint.

Represents a SharePoint list. A list is a type of SP.SecurableObject.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Endpoint URI

http://<site url>/web/lists(guid'<list id>')

Supported HTTP methods

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Request examples

GET request example: Get a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can use the GetByTitle method from the ListCollection resource to get a list by its title. Example: …/web/lists/getbytitle('Access Requests').

POST request example: Create a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true, 'BaseTemplate': 100,
    'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test title' }",
  headers: { "content-type": "application/json;odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MERGE request example: Change a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true, 'BaseTemplate': 100,
    'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test title' }",
  headers: { 
    "IF-MATCH”: "*",
    "X-HTTP-Method": "MERGE",
    "content-type": "application/json;odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

DELETE request example: Delete a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    ?@target='<host web url>'",
  method: "POST",
  headers: { 
    "IF-MATCH”: "*",
    "X-HTTP-Method": "DELETE"
  },
  success: successHandler,
  error: errorHandler
});

If you want to recycle a list and get the GUID of the recycle bin item, use the list's Recycle method to remove the file.

List 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
    /lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/<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

AllowContentTypes

Boolean

R

Yes

Gets a value that specifies whether the list supports content types.

BaseTemplate

Int32

R

Yes

Gets the list definition type on which the list is based. Represents a ListTemplateType value. See ListTemplateType in the .NET client object model reference for template type values.

BaseType

Int32

R

Yes

Gets the base type for the list. Represents an SP.BaseType value: Generic List = 0; Document Library = 1; Discussion Board = 3; Survey = 4; Issue = 5.

BrowserFileHandling

Int32

R

No

Gets a value that specifies the override of the web application's BrowserFileHandling property at the list level. Represents an SP.BrowserFileHandling value: Permissive = 0; Strict = 1.

ContentTypes

SP.ContentTypeCollection

R

No

Gets the content types that are associated with the list.

ContentTypesEnabled

Boolean

RW

Yes

Gets or sets a value that specifies whether content types are enabled for the list.

Created

DateTime

R

Yes

Gets a value that specifies when the list was created.

DataSource

SP.ListDataSource

R

No

Gets the data source associated with the list, or null if the list is not a virtual list. Returns null if the HasExternalDataSource property is false.

DefaultContentApprovalWorkflowId

GUID

RW

Yes

Gets or sets a value that specifies the default workflow identifier for content approval on the list. Returns an empty GUID if there is no default content approval workflow.

DefaultDisplayFormUrl

String

RW

No

Gets or sets a value that specifies the location of the default display form for the list. Clients specify a server-relative URL, and the server returns a site-relative URL

DefaultEditFormUrl

String

RW

No

Gets or sets a value that specifies the URL of the edit form to use for list items in the list. Clients specify a server-relative URL, and the server returns a site-relative URL.

DefaultNewFormUrl

String

RW

No

Gets or sets a value that specifies the location of the default new form for the list. Clients specify a server-relative URL, and the server returns a site-relative URL.

DefaultView

SP.View

R

No

DefaultViewUrl

String

R

No

Gets the URL of the default view for the list.

Description

String

RW

Yes

Gets or sets a value that specifies the description of the list.

Direction

String

RW

Yes

Gets or sets a value that specifies the reading order of the list. Returns "NONE", "LTR", or "RTL".

DocumentTemplateUrl

String

RW

Yes

Gets or sets a value that specifies the server-relative URL of the document template for the list. Returns a server-relative URL if the base type is DocumentLibrary, otherwise returns null.

DraftVersionVisibility

Int32

RW

Yes

Gets or sets a value that specifies the minimum permission required to view minor versions and drafts within the list. Represents an SP.DraftVisibilityType value: Reader = 0; Author = 1; Approver = 2.

EffectiveBasePermissions

SP.BasePermissions

R

No

Gets a value that specifies the effective permissions on the list that are assigned to the current user.

EffectiveBasePermissionsForUI

SP.BasePermissions

R

No

EnableAttachments

Boolean

RW

Yes

Gets or sets a value that specifies whether list item attachments are enabled for the list.

EnableFolderCreation

Boolean

RW

Yes

Gets or sets a value that specifies whether new list folders can be added to the list.

EnableMinorVersions

Boolean

RW

Yes

Gets or sets a value that specifies whether minor versions are enabled for the list.

EnableModeration

Boolean

RW

Yes

Gets or sets a value that specifies whether content approval is enabled for the list.

EnableVersioning

Boolean

RW

Yes

Gets or sets a value that specifies whether historical versions of list items and documents can be created in the list.

EntityTypeName

String

R

Yes

EventReceivers

SP.EventReceiverDefinitionCollection

R

No

Fields

SP.FieldCollection

R

No

Gets a value that specifies the collection of all fields in the list.

FirstUniqueAncestorSecurableObject

SP.SecurableObject

R

No

Gets the object where role assignments for this object are defined. If role assignments are defined directly on the current object, the current object is returned.

ForceCheckout

Boolean

RW

Yes

Gets or sets a value that indicates whether forced checkout is enabled for the document library.

Forms

SP.FormCollection

R

No

Gets a value that specifies the collection of all list forms in the list.

HasExternalDataSource

Boolean

R

Yes

Gets a value that specifies whether the list is an external list.

HasUniqueRoleAssignments

Boolean

R

No

Gets a value that specifies whether the role assignments are uniquely defined for this securable object or inherited from a parent securable object.

Hidden

Boolean

RW

Yes

Gets or sets a Boolean value that specifies whether the list is hidden. If true, the server sets the OnQuickLaunch property to false.

Id

GUID

R

Yes

Gets the GUID that identifies the list in the database.

ImageUrl

String

R

Yes

Gets a value that specifies the URI for the icon of the list.

InformationRightsManagementSettings

SP.InformationRightsManagementSettings

R

No

IrmEnabled

Boolean

RW

Yes

IrmExpire

Boolean

RW

Yes

IrmReject

Boolean

RW

Yes

IsApplicationList

Boolean

RW

Yes

Gets or sets a value that specifies a flag that a client application can use to determine whether to display the list.

IsCatalog

Boolean

R

Yes

Gets a value that specifies whether the list is a gallery.

IsPrivate

Boolean

R

Yes

IsSiteAssetsLibrary

Boolean

R

No

Gets a value that indicates whether the list is designated as a default asset location for images or other files which the users upload to their wiki pages.

ItemCount

Int32

R

Yes

Gets a value that specifies the number of list items in the list.

Items

SP.ListItemCollection

R

No

Gets all the items in the list.

You can use OData query operations to filter items (example: …/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/items?$filter=Status eq 'not started'&$select=Title&$top=5).

LastItemDeletedDate

DateTime

R

Yes

Gets a value that specifies the last time a list item was deleted from the list.

LastItemModifiedDate

DateTime

RW

Yes

Gets a value that specifies the last time a list item, field, or property of the list was modified.

ListItemEntityTypeFullName

String

R

Yes

MultipleDataList

Boolean

RW

Yes

Gets or sets a value that indicates whether the list in a Meeting Workspace site contains data for multiple meeting instances within the site.

NoCrawl

Boolean

RW

Yes

Gets or sets a value that specifies that the crawler must not crawl the list.

OnQuickLaunch

Boolean

RW

No

Gets or sets a value that specifies whether the list appears on the Quick Launch of the site. If true, the server sets the Hidden property to false.

ParentWeb

SP.Web

R

No

Gets a value that specifies the site that contains the list.

ParentWebUrl

String

R

Yes

Gets a value that specifies the server-relative URL of the site that contains the list.

RoleAssignments

SP.RoleAssignmentCollection

R

No

Gets the role assignments for the securable object.

RootFolder

SP.Folder

R

No

Gets the root folder that contains the files in the list and any related files.

SchemaXml

String

R

No

Gets a value that specifies the list schema of the list.

ServerTemplateCanCreateFolders

Boolean

R

Yes

Gets a value that indicates whether folders can be created within the list.

TemplateFeatureId

GUID

R

Yes

Gets a value that specifies the feature identifier of the feature that contains the list schema for the list. Returns an empty GUID if the list schema is not contained within a feature.

Title

String

RW

Yes

Gets or sets the displayed title for the list. Its length must be <= 255 characters.

UserCustomActions

SP.UserCustomActionCollection

R

No

Gets a value that specifies the collection of all user custom actions for the list.

ValidationFormula

String

RW

No

Gets or sets a value that specifies the data validation criteria for a list item. Its length must be <= 1023.

ValidationMessage

String

RW

No

Gets or sets a value that specifies the error message returned when data validation fails for a list item. Its length must be <= 1023.

Views

SP.ViewCollection

R

No

Gets a value that specifies the collection of all public views on the list and personal views of the current user on the list.

WorkflowAssociations

SP.Workflow.WorkflowAssociationCollection

R

No

Gets a value that specifies the collection of all workflow associations for the list.

List methods

AddItem
BreakRoleInheritance
DeleteObject
GetChanges
GetItemById
GetItems
GetListItemChangesSinceToken
GetRelatedFields
GetUserEffectivePermissions
GetView
Recycle
RenderListData
RenderListFormData
ReserveListItemId
ResetRoleInheritance

AddItem method

The recommended way to add a list item is to send a POST request to the ListItemCollection resource endpoint, as shown in ListItemCollection request examples.

BreakRoleInheritance method

Creates unique role assignments for the securable object.

Endpoint

/breakroleinheritance(copyroleassignments, clearsubscopes)

Parameters

copyroleassignments

Type: Boolean
true to copy the role assignments from the parent securable object; false to remove the inherited role assignments except one that contains the current user.

clearsubscopes

Type: Boolean
Optional. true to make all child securable objects inherit role assignments from the current object; false (default) to leave role assignments unchanged for child securable objects that do not inherit role assignments from their parent object.

HTTP method

POST

Response

None


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'a290086b-2d43-4151-add4-893474a930a9')
    /breakroleinheritance(copyroleassignments=false, clearsubscopes=true)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

DeleteObject method

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

GetChanges method

Returns the collection of changes from the change log that have occurred within the list, based on the specified query.

Endpoint

/getchanges

Parameters

query

Type: SP.ChangeQuery
The change query. Pass this parameter in the request body, as shown in the request example.

HTTP method

POST

Response

Type: SP.ChangeCollection
The changes to the list that match the criteria of the specified change query.


  Request example

var metadata = "{ 'query' : { '__metadata': { 'type': 'SP.ChangeQuery' },
    'Add': 'True', 'Item': 'True' }}";

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /getchanges
    ?@target='<host web url>'",
  method: "POST",
  body: metadata,
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});


  Response example

{"d":
  {"results":[{
    "__metadata":{
      "id":"https://<site url>/_api/SP.ChangeItema7e7c6e9-2c41-47c3-aae9-2b4a63b7a087",
      "uri":"https://<site url>/_api/SP.ChangeItem",
      "type":"SP.ChangeItem"
    },
    "ChangeToken":{"__metadata":{"type":"SP.ChangeToken"}, "StringValue":"1;3;482e418a-0900-414b-8902-02248c2e44e8;634955266749500000;5749111"},
    "ChangeType":1,
    "SiteId":"ce11bfbb-cf9d-4b2b-a642-8673bd48cceb",
    "Time":"2013-02-03T22:17:54Z",
    "ItemId":1,
    "ListId":"482e418a-0900-414b-8902-02248c2e44e8",
    "WebId":"a975b994-fc67-4203-a519-b160175ca967"
  }]
}}

GetItemById method

Returns the list item with the specified list item identifier.

Endpoint

/getitembyid(<item id>)

Parameters

Type: Int32
The ID of the list item.

HTTP method

GET

Response

Type: SP.ListItem
The list item with the specified ID.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'a290086b-2d43-4151-add4-893474a930a9')
    /getitembyid(2)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can pass the list item ID to the ListItemCollection resource. Example: …/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/items(2).

GetItems method

Returns a collection of items from the list based on the specified query.

Endpoint

/getitems

Parameters

query

Type: SP.CamlQuery
The filter query. Pass this parameter in the request body, as shown in the request example.

HTTP method

POST

Response

Type: SP.ListItemCollection
The list items that match the specified query.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'47f89cf2-359d-4792-9dc4-8da877a5050a')
    /getitems
    ?@target='<host web url>'",
  method: "POST",
  body: "{ 'query' : {'__metadata': { 'type': 'SP.CamlQuery' }, "ViewXml": "<View><Query><Where><Contains><FieldRef Name='Status'/><Value Type='CHOICE'>in progress</Value></Contains></Where></Query></View>" } }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

GetListItemChangesSinceToken method

Endpoint

/getlistitemchangessincetoken

Parameters

query

Type: SP.ChangeLogItemQuery
The query that contains the change token. Pass this parameter in the request body, as shown in the request example.

HTTP method

POST

Response

Type: GetListItemChangesSinceTokenResult
A Stream that contains an XML representation of the changes to the list items that have happened after the specified change.


  Request example

var metadata = "{ 'query': { '__metadata': { 'type': 'SP.ChangeLogItemQuery' },
    'ChangeToken': '1;3;79cc20e6-adda-438e-8a96-792041b33168;635103901830230000;33050019' }}";

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /getlistitemchangessincetoken
    ?@target='<host web url>'",
  method: "POST",
  body: metadata,
  headers: { "content-type": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

See Synchronize SharePoint items using the REST service for an example of how to specify a filtered query.


  Response example

<?xml version="1.0" encoding="utf-8" ?>
<GetListItemChangesSinceTokenResult>
  <listitems MinTimeBetweenSyncs='0' RecommendedTimeBetweenSyncs='180' MaxBulkDocumentSyncSize='500' MaxRecommendedEmbeddedFileSize='500' EffectivePermMask='FullMask' xmlns:s='uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882' xmlns:dt='uuid:C2F41010-65B3-11d1-A29F-00AA00C14882' xmlns:rs='urn:schemas-microsoft-com:rowset' xmlns:z='#RowsetSchema'>
    <Changes LastChangeToken="1;3;79cc20e6-adda-438e-8a96-792041b33168;635110802324330000;33811711">
    <List DocTemplateUrl="" DefaultViewUrl="/Lists/TestList/AllItems.aspx" MobileDefaultViewUrl="" ID="{79CC20E6-ADDA-438E-8A96-792041B33168}" Title="TestList" Description="" ImageUrl="/_layouts/15/images/itgen.png?rev=26" Name="{79CC20E6-ADDA-438E-8A96-792041B33168}" BaseType="0" FeatureId="00bfea71-de22-43b2-a848-c05709900100" ServerTemplate="100" Created="20130725 22:22:35" Modified="20130802 22:43:52" LastDeleted="20130725 22:22:35" Version="4" Direction="none" ThumbnailSize="" WebImageWidth="" WebImageHeight="" Flags="545263616" ItemCount="2" AnonymousPermMask="0" RootFolder="/Lists/TestList" ReadSecurity="1" WriteSecurity="1" Author="11" EventSinkAssembly="" EventSinkClass="" EventSinkData="" EmailAlias="" WebFullUrl="/" WebId="a975b994-fc67-4203-a519-b160175ca967" SendToLocation="" ScopeId="ad9949be-be16-4946-b5de-66c912eda54a" MajorVersionLimit="0" MajorWithMinorVersionsLimit="0" WorkFlowId="" HasUniqueScopes="False" NoThrottleListOperations="False" HasRelatedLists="" Followable="False" AllowDeletion="True" AllowMultiResponses="False" EnableAttachments="True" EnableModeration="False" EnableVersioning="False" HasExternalDataSource="False" Hidden="False" MultipleDataList="False" Ordered="False" ShowUser="True" EnablePeopleSelector="False" EnableResourceSelector="False" EnableMinorVersion="False" RequireCheckout="False" ThrottleListOperations="False" ExcludeFromOfflineClient="False" CanOpenFileAsync="True" EnableFolderCreation="False" IrmEnabled="False" IsApplicationList="False" PreserveEmptyValues="False" StrictTypeCoercion="False" EnforceDataValidation="False" MaxItemsPerThrottledOperation="5000">
      <Fields>
        <Field ID="{03e45e84-1992-4d42-9116-26f756012634}" RowOrdinal="0" Type="ContentTypeId" Sealed="TRUE" ReadOnly="TRUE" Hidden="TRUE" DisplayName="Content Type ID" Name="ContentTypeId" DisplaceOnUpgrade="TRUE" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="ContentTypeId" ColName="tp_ContentTypeId" FromBaseType="TRUE"/>
        <Field ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}" Type="Text" Name="Title" DisplayName="Title" Required="TRUE" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="Title" FromBaseType="TRUE" ColName="nvarchar1"/>
        <Field ID="{34ad21eb-75bd-4544-8c73-0e08330291fe}" ReadOnly="TRUE" Type="Note" Name="_ModerationComments" DisplayName="Approver Comments" Hidden="TRUE" CanToggleHidden="TRUE" Filterable="FALSE" Sortable="FALSE" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="_ModerationComments" FromBaseType="TRUE" ColName="ntext1"/>
        <Field ID="{39360f11-34cf-4356-9945-25c44e68dade}" ReadOnly="TRUE" Hidden="TRUE" Type="Text" Name="File_x0020_Type" DisplaceOnUpgrade="TRUE" DisplayName="File Type" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="File_x0020_Type" FromBaseType="TRUE" ColName="nvarchar2"/>
        <Field ID="{fc2e188e-ba91-48c9-9dd3-16431afddd50}" Name="WorkAddress" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="WorkAddress" Group="Core Contact and Calendar Columns" DisplayName="Address" Type="Note" NumLines="2" Sortable="FALSE" ColName="ntext2" RowOrdinal="0"/>
        <Field ID="{fce16b4c-fe53-4793-aaab-b4892e736d15}" Name="EMail" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="EMail" Group="Core Contact and Calendar Columns" DisplayName="E-Mail" ReadOnly="FALSE" Type="Text" FromBaseType="TRUE" AllowDeletion="TRUE" ColName="nvarchar3" RowOrdinal="0"/>
        <Field Type="Lookup" DisplayName="anewishlisttitle" Required="FALSE" EnforceUniqueValues="FALSE" List="{482e418a-0900-414b-8902-02248c2e44e8}" ShowField="Title" UnlimitedLengthInDocumentLibrary="FALSE" RelationshipDeleteBehavior="None" ID="{9919f3f8-88fb-43fc-b4cb-658b1db1bfe3}" SourceID="{79cc20e6-adda-438e-8a96-792041b33168}" StaticName="anewishlisttitle" Name="anewishlisttitle" ColName="int1" RowOrdinal="0"/>
        <Field Type="Lookup" DisplayName="Books title" Required="FALSE" EnforceUniqueValues="FALSE" List="{90146606-81fd-410d-9fdd-d03b6349fbcd}" ShowField="Title" UnlimitedLengthInDocumentLibrary="FALSE" RelationshipDeleteBehavior="None" ID="{879a1cba-91b6-4c0a-99fb-29f877aae3ea}" SourceID="{79cc20e6-adda-438e-8a96-792041b33168}" StaticName="Books_x0020_title" Name="Books_x0020_title" ColName="int2" RowOrdinal="0"/>
        <Field ID="{1d22ea11-1e32-424e-89ab-9fedbadb6ce1}" ColName="tp_ID" RowOrdinal="0" ReadOnly="TRUE" Type="Counter" Name="ID" PrimaryKey="TRUE" DisplayName="ID" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="ID" FromBaseType="TRUE"/>
        <Field ID="{c042a256-787d-4a6f-8a8a-cf6ab767f12d}" Type="Computed" DisplayName="Content Type" Name="ContentType" DisplaceOnUpgrade="TRUE" RenderXMLUsingPattern="TRUE" Sortable="FALSE" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="ContentType" Group="_Hidden" PITarget="MicrosoftWindowsSharePointServices" PIAttribute="ContentTypeID" FromBaseType="TRUE">
          <FieldRefs>
            <FieldRef Name="ContentTypeId"/>
          </FieldRefs>
          <DisplayPattern>
            <MapToContentType>
              <Column Name="ContentTypeId"/>
            </MapToContentType>
          </DisplayPattern>
        </Field>
        <…>
      </Fields>
      <RegionalSettings>
        <Language>1033</Language>
        <Locale>1033</Locale>
        <AdvanceHijri>0</AdvanceHijri>
        <CalendarType>1</CalendarType>
        <Time24>False</Time24>
        <TimeZone>480</TimeZone>
        <SortOrder>2070</SortOrder>
        <Presence>True</Presence>
      </RegionalSettings>
      <ServerSettings>
        <ServerVersion>16.0.1810.1236</ServerVersion>
        <RecycleBinEnabled>True</RecycleBinEnabled>
        <ServerRelativeUrl>/</ServerRelativeUrl>
       </ServerSettings>
      </List>
    </Changes>
    <rs:data ItemCount="1">
      <z:row ows_ContentTypeId='0x0100C8CFB1DE383F1B49A44ABD2EB9AC7322' ows_Title='<item title>' ows_ID='2' ows_ContentType='Item' ows_Modified='2013-07-25T23:21:50Z' ows_Created='2013-07-25T23:21:50Z' ows_Author='<author>' ows_Editor='<editor>' ows_owshiddenversion='1' ows_WorkflowVersion='1' ows__UIVersion='512' ows__UIVersionString='1.0' ows_Attachments='0' ows__ModerationStatus='0' ows_LinkTitleNoMenu='<item title>' ows_LinkTitle='<item title>' ows_LinkTitle2='<item title>' ows_SelectTitle='2' ows_Order='200.000000000000' ows_GUID='{D38981C3-2735-4FDF-9B41-91F3ADA8F3F0}' ows_FileRef='2;#Lists/TestList/2_.000' ows_FileDirRef='2;#Lists/TestList' ows_Last_x0020_Modified='2;#2013-07-25T23:21:50Z' ows_Created_x0020_Date='2;#2013-07-25T23:21:50Z' ows_FSObjType='2;#0' ows_SortBehavior='2;#0' ows_PermMask='0x7fffffffffffffff' ows_FileLeafRef='2;#2_.000' ows_UniqueId='2;#{4D719C3B-B8AB-46A0-A080-402DF6EE31C1}' ows_ProgId='2;#' ows_ScopeId='2;#{AD9949BE-BE16-4946-B5DE-66C912EDA54A}' ows__EditMenuTableStart='2_.000' ows__EditMenuTableStart2='2' ows__EditMenuTableEnd='2' ows_LinkFilenameNoMenu='2_.000' ows_LinkFilename='2_.000' ows_LinkFilename2='2_.000' ows_ServerUrl='/Lists/TestList/2_.000' ows_EncodedAbsUrl='https://<site url>.sharepoint.com/Lists/TestList/2_.000' ows_BaseName='2_' ows_MetaInfo='2;#' ows__Level='1' ows__IsCurrentVersion='1' ows_ItemChildCount='2;#0' ows_FolderChildCount='2;#0' ows_ServerRedirected='0' />
    </rs:data>
  </listitems>
</GetListItemChangesSinceTokenResult>

GetRelatedFields method

Returns a collection of lookup fields that use this list as a data source and that have FieldLookup.IsRelationship set to true.

Endpoint

/getrelatedfields

Parameters

None

HTTP method

GET

Response

Type: SP.RelatedFieldCollection
A collection of SP.RelatedField objects with information about the relationship between a field in a list and a lookup field in another list.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /getrelatedfields
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetUserEffectivePermissions method

Endpoint

/getusereffectivepermissions(@user)?@user='<user login name>'

Parameters

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

HTTP method

GET

Response

Type: SP.BasePermissions
The set of permissions for the specified user: Int64 values for high- and low-order parts of the permissions.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /getusereffectivepermissions(@user)?@user='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
});

GetView method

Returns the list view with the specified view identifier.

Endpoint

/getview('<view id>')

Parameters

Type: String
The unique identifier for the list view.

HTTP method

GET

Response

Type: SP.View
The specified list view.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /getview('4814949d-3e17-444c-a1a3-cb69bc77e95f')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or you can just specify the view ID on the ViewCollection resource. Example: …/_api/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/views('4814949d-3e17-444c-a1a3-cb69bc77e95f')

Recycle method

Moves the list to the Recycle Bin and returns the identifier of the new Recycle Bin item.

Endpoint

/recycle

Parameters

None

HTTP method

POST

Response

Type: GUID
The GUID of the recycled list.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /recycle
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

RenderListData method

Endpoint

/renderlistdata('<view xml>')

Parameters

Type: String
A CAML query that defines the items and fields that you want returned.

HTTP method

POST

Response

Type: String
The requested list data in the view defined by the specified XML.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /renderlistdata(@viewXml)?@viewXml='<View><RowLimit>10</RowLimit></View>'
    &@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

RenderListFormData method

Endpoint

/renderlistformdata(itemid, formid, mode)

Parameters

itemid

Type: Int32
The identifier of the list item to be rendered.

formid

Type: String
The identifier of the form.

mode

Type: Int32
The SP.ControlMode of the control used to display the item: 1 = Display; 2 = Edit; 3 = New.

HTTP method

POST

Response

Type: String
The field values and field schema attributes for a list item.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /renderlistformdata(itemid=4, formid='e8b2f6e3-1081-4b18-833b-475f76473cde', mode=2)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ReserveListItemId method

Reserves a list item ID for idempotent list item creation.

Endpoint

/reservelistitemid

Parameters

None

HTTP method

POST

Response

Type: Int32
The list item identifier to be reserved.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /reservelistitemid
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ResetRoleInheritance method

Resets the role inheritance for the securable object and inherits role assignments from the parent securable object.

Endpoint

/resetroleinheritance

Parameters

None

HTTP method

POST

Response

None


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /resetroleinheritance
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a List resource in JSON format.

{"d":{
  "__metadata":{
    "id":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')",
    "uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')",
    "etag":"\"0\"",
    "type":"SP.List"
  },
  "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/FirstUniqueAncestorSecurableObject"}},
  "RoleAssignments":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/RoleAssignments"}},
  "ContentTypes":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/ContentTypes"}},
  "DefaultView":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/DefaultView"}},
  "EventReceivers":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/EventReceivers"}},
  "Fields":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/Fields"}},
  "Forms":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/Forms"}},
  "InformationRightsManagementSettings":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/InformationRightsManagementSettings"}},
  "AllowContentTypes":true, 
  "BaseTemplate":100, 
  "BaseType":0, 
  "ContentTypesEnabled":false, 
  "Created":"2013-02-02T21:11:56Z",
  "DefaultContentApprovalWorkflowId":"00000000-0000-0000-0000-000000000000",
  "Description":"",
  "Direction":"none",
  "DocumentTemplateUrl":null, 
  "DraftVersionVisibility":0, 
  "EnableAttachments":true, 
  "EnableFolderCreation":false, 
  "EnableMinorVersions":false, 
  "EnableModeration":false, 
  "EnableVersioning":false,
  "EntityTypeName":"ANewList",
  "ForceCheckout":false, 
  "HasExternalDataSource":false, 
  "Hidden":false, 
  "Id":"8ade7551-f53c-48c5-9d2b-e89f6528cf47",
  "ImageUrl":"/_layouts/15/images/itgen.png?rev=23",
  "IrmEnabled":false, 
  "IrmExpire":false, 
  "IrmReject":false, 
  "IsApplicationList":false, 
  "IsCatalog":false, 
  "IsPrivate":false, 
  "ItemCount":1, 
  "LastItemDeletedDate":"2013-02-02T21:11:56Z",
  "LastItemModifiedDate":"2013-02-03T22:17:55Z",
  "ListItemEntityTypeFullName":"SP.Data.ANewListItem",
  "MultipleDataList":false, 
  "NoCrawl":false, 
  "ParentWebUrl":"/",
  "ServerTemplateCanCreateFolders":true, 
  "TemplateFeatureId":"00bfea71-de22-43b2-a848-c05709900100",
  "Title":"ANewList"
}}

Represents a collection of lists.

Endpoint URI  |  Methods  |  OData representation

Endpoint URI

http://<site url>/web/lists

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get the lists at the root site

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

GET request example: Get a list by title

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

GET request example: Get a list by ID

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST request example: Create a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true, 'BaseTemplate': 100,
    'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test title' }",
  headers: { "content-type": "application/json;odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ListCollection methods

EnsureSiteAssetsLibrary
EnsureSitePagesLibrary
GetById
GetByTitle

EnsureSiteAssetsLibrary method

Gets a list that is the default asset location for images or other files, which the users upload to their wiki pages.

Endpoint

/ensuresiteassetslibrary

Parameters

None

HTTP method

POST

Response

Type: SP.List
The list that is the default location for wiki page assets.


  Request example

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

EnsureSitePagesLibrary method

Gets a list that is the default location for wiki pages.

Endpoint

/ensuresitepageslibrary

Parameters

None

HTTP method

POST

Response

Type: SP.List
The list that is the default location for wiki pages.


  Request example

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

GetById method

Returns the list with the specified list identifier.

Endpoint

/getbyid

Parameters

Type: String
The list identifier.

HTTP method

GET

Response

Type: SP.List
The list with the specified identifier.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    /getbyid('51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can just pass the list ID to the ListCollection resource. Example: …/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b').

GetByTitle method

Returns the list with the specified title from the collection.

Endpoint

/getbytitle

Parameters

Type: String
The list title.

HTTP method

GET

Response

Type: SP.List
The list with the specified title.


  Request example

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

OData representation

The following example represents an ListCollection resource in JSON format.

{"d":{
  "results":[{
    "__metadata":{"id":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')",
    "uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-
4bfa4e69d48b')",
    "etag":"\"6\"",
    "type":"SP.List"
  },
  "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/FirstUniqueAncestorSecurableObject"}},
  "RoleAssignments":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/RoleAssignments"}},
  "ContentTypes":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/ContentTypes"}},
  "DefaultView":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/DefaultView"}},
  "EventReceivers":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/EventReceivers"}},
  "Fields":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/Fields"}},
  "Forms":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/Forms"}},
  "InformationRightsManagementSettings":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/InformationRightsManagementSettings"}},
  "Items":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/Items"}},
  "ParentWeb":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/ParentWeb"}},
  "RootFolder":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/RootFolder"}},
  "UserCustomActions":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/UserCustomActions"}},
  "Views":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/Views"}},
  "WorkflowAssociations":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/WorkflowAssociations"}},
  "AllowContentTypes":true,
  "BaseTemplate":160,"BaseType":0,
  "ContentTypesEnabled":true,
  "Created":"2013-06-10T17:14:49Z",
  "DefaultContentApprovalWorkflowId":"00000000-0000-0000-0000-000000000000",
  "Description":"Use this list to track access requests to a site or uniquely permissioned items in the site.",
  "Direction":"none",
  "DocumentTemplateUrl":null,
  "DraftVersionVisibility":0,
  "EnableAttachments":false,
  "EnableFolderCreation":false,
  "EnableMinorVersions":false,
  "EnableModeration":false,
  "EnableVersioning":true,
  "EntityTypeName":"Access_x0020_Requests",
  "ForceCheckout":false,
  "HasExternalDataSource":false,
  "Hidden":true,
  "Id":"51925dd7-2108-481a-b1ef-4bfa4e69d48b",
  "ImageUrl":"/_layouts/15/images/itgen.gif?rev=26",
  "IrmEnabled":false,
  "IrmExpire":false,
  "IrmReject":false,
  "IsApplicationList":false,
  "IsCatalog":false,
  "IsPrivate":false,
  "ItemCount":3,
  "LastItemDeletedDate":"2013-06-10T17:14:49Z",
  "LastItemModifiedDate":"2013-06-10T17:20:48Z",
  "ListItemEntityTypeFullName":"SP.Data.Access_x0020_RequestsItem",
  "MultipleDataList":false,
  "NoCrawl":true,
  "ParentWebUrl":"/",
  "ServerTemplateCanCreateFolders":true,
  "TemplateFeatureId":"a0f12ee4-9b60-4ba4-81f6-75724f4ca973",
  "Title":"Access Requests"},
  {
    "__metadata":{
      "id":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')",
      "uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-
02248c2e44e8')",
      "etag":"\"1\"",
      "type":"SP.List"
    },
    "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902- 
02248c2e44e8')/FirstUniqueAncestorSecurableObject"}},
    "RoleAssignments":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/RoleAssignments"}},
    "ContentTypes":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/ContentTypes"}},
    "DefaultView":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/DefaultView"}},
    "EventReceivers":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/EventReceivers"}},
    "Fields":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/Fields"}},
    "Forms":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/Forms"}},
    "InformationRightsManagementSettings":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/InformationRightsManagementSettings"}},
    "Items":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/Items"}},
    "ParentWeb":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/ParentWeb"}},
    "RootFolder":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/RootFolder"}},
    "UserCustomActions":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/UserCustomActions"}},
    "Views":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/Views"}},
    "WorkflowAssociations":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/WorkflowAssociations"}},
    "AllowContentTypes":true,
    "BaseTemplate":100,
    "BaseType":0,
    "ContentTypesEnabled":false,
    "Created":"2013-02-02T21:11:56Z",
    "DefaultContentApprovalWorkflowId":"00000000-0000-0000-0000-000000000000",
    "Description":"",
    "Direction":"none",
    "DocumentTemplateUrl":null,
    "DraftVersionVisibility":0,
    "EnableAttachments":true,
    "EnableFolderCreation":false,
    "EnableMinorVersions":false,
    "EnableModeration":false,
    "EnableVersioning":false,
    "EntityTypeName":"AList",
    "ForceCheckout":false,
    "HasExternalDataSource":false,
    "Hidden":false,
    "Id":"482e418a-0900-414b-8902-02248c2e44e8",
    "ImageUrl":"/_layouts/15/images/itgen.png?rev=23",
    "IrmEnabled":false,
    "IrmExpire":false,
    "IrmReject":false,
    "IsApplicationList":false,
    "IsCatalog":false,
    "IsPrivate":false,
    "ItemCount":3,
    "LastItemDeletedDate":"2013-02-02T21:11:56Z",
    "LastItemModifiedDate":"2013-06-26T22:31:03Z",
    "ListItemEntityTypeFullName":"SP.Data.AListListItem",
    "MultipleDataList":false,
    "NoCrawl":false,
    "ParentWebUrl":"/",
    "ServerTemplateCanCreateFolders":true,
    "TemplateFeatureId":"00bfea71-de22-43b2-a848-c05709900100",
    "Title":"AList"
  }]
}}

Represents an item or row in a list. A list item is a type of SP.SecurableObject.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Note Note

The OData $skip query option does not work with this endpoint.

Endpoint URI

http://<site url>/web/lists(guid'<list id>')/items(<item id>)
http://<site url>/web/lists/getbytitle('<list title>')/items(<item id>)

Supported HTTP methods

GET  |  POST  |  DELETE  |  MERGE

Request examples

GET request example: Get a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST request example: Create a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.Data.Team_x0020_tasksListItem' },
    'Title': 'Teams incorporate feedback', 'AssignedToId': {"results":[1]},
    'StartDate':'2014-01-29T08:00:00Z', 'DueDate':'2014-01-31T08:00:00Z',
    'PredecessorsId': {"results":[4]}}",
  headers: { 
    "accept": "application/json;odata=verbose",
    "content-type": "application/json;odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});
NoteNote

To create or change a list item, you must know the ListItemEntityTypeFullName property of the list and pass that as the value of type in the HTTP request body.

See ListItemCollection request examples for an example that shows how to create a list item.

MERGE request example: Change a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.Data.Team_x0020_tasksListItem' },
    'Priority': '(1) High', 'Status': 'In Progress', 'PercentComplete': 0.3 }",
  headers: { 
    "IF-MATCH": "*",
    "content-type": "application/json;odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});
NoteNote

To create or change a list item, you must know the ListItemEntityTypeFullName property of the list and pass that as the value of type in the HTTP request body.

DELETE request example: Delete a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    ?@target='<host web url>'",
  method: "POST",
  headers: { 
    "IF-MATCH”: "*",
    "X-HTTP-Method": "DELETE"
  },
  success: successHandler,
  error: errorHandler
});

If you want to get the GUID of the recycle operation, use the item's Recycle method.

ListItem properties

Property

Type

R/W

Returned with resource

Description

AttachmentFiles

SP.AttachmentCollection

R

No

Specifies the collection of attachments that are associated with the list item.

ContentType

SP.ContentType

R

No

Gets a value that specifies the content type of the list item.

DisplayName

String

R

Yes (displayed as the "Title" value)

Gets a value that specifies the display name of the list item.

EffectiveBasePermissions

SP.BasePermissions

R

Yes

Gets a value that specifies the effective permissions on the list item that are assigned to the current user.

EffectiveBasePermissionsForUI

SP.BasePermissions

R

Yes

Gets the effective base permissions for the current user, as they should be displayed in UI.

FieldValuesAsHtml

SP.FieldStringValues

R

No

Gets the values for the list item as HTML.

FieldValuesAsText

SP.FieldStringValues

R

No

Gets the list item's field values as a collection of string values.

FieldValuesForEdit

SP.FieldStringValues

R

No

Gets the formatted values to be displayed in an edit form.

File

SP.File

R

No

Gets the file that is represented by the item from a document library.

FileSystemObjectType

Int32

R

Yes

Gets a value that specifies whether the list item is a file or a list folder. Represents an SP.FileSystemObjectType value: Invalid = -1; File = 0; Folder = 1; Web = 2.

FirstUniqueAncestorSecurableObject

SP.SecurableObject

R

No

Gets the object where role assignments for this object are defined. If role assignments are defined directly on the current object, the current object is returned.

Folder

SP.Folder

R

No

Gets a folder object that is associated with a folder item.

HasUniqueRoleAssignments

Boolean

R

No

Gets a value that specifies whether the role assignments are uniquely defined for this securable object or inherited from a parent securable object.

Id

Int32

R

Yes

Gets a value that specifies the list item identifier.

ParentList

SP.List

R

No

Gets the parent list that contains the list item.

RoleAssignments

SP.RoleAssignmentCollection

R

No

Gets the role assignments for the securable object.

ListItem methods

BreakRoleInheritance
DeleteObject
GetUserEffectivePermissions
Recycle
ResetRoleInheritance
ValidateUpdateListItem

BreakRoleInheritance method

Creates unique role assignments for the securable object.

Endpoint

/breakroleinheritance(copyroleassignments, clearsubscopes)

Parameters

copyroleassignments

Type: Boolean
true to copy the role assignments from the parent securable object; false to remove the inherited role assignments except one that contains the current user.

clearsubscopes

Type: Boolean
true to make all child securable objects inherit role assignments from the current object; false to leave role assignments unchanged for child securable objects that do not inherit role assignments from their parent object.

HTTP method

POST

Response

None


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /breakroleinheritance(copyroleassignments=true, clearsubscopes=false)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,par
  error: errorHandler
});

DeleteObject method

The recommended way to delete a list item is to send a DELETE request to the ListItem resource endpoint, as shown in ListItem request examples.

GetUserEffectivePermissions method

Gets the effective permissions that a specified user has on the list item.

Endpoint

/getusereffectivepermissions(@v)?@v='<user login name>'

Parameters

Type: String
The login name of the user to get permissions for. For example:
  SharePoint Online: …/getusereffectivepermissions(@v)?@v='i%3A0%23.f%7Cmembership%7C<user>%40<domain>.onmicrosoft.com'
  On-premises using claims: …/getusereffectivepermissions(@v)?@v='i%3A0%23.w%7C<domain\user>'
  On-premises using forms: …/getusereffectivepermissions(@v)?@v='<domain\user>'

HTTP method

GET

Response

Type: SP.BasePermissions
The base permissions for the list item for the specified user: Int64 values for high- and low-order parts of the permissions.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /getusereffectivepermissions(@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
});

Recycle method

Moves the list item to the Recycle Bin and returns the identifier of the new Recycle Bin item.

Endpoint

/recycle

Parameters

None

HTTP method

POST

Response

Type: GUID
The GUID of the recycled list item.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /recycle
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ResetRoleInheritance method

Resets the role inheritance for the securable object and inherits role assignments from the parent securable object.

Endpoint

/resetroleinheritance

Parameters

None

HTTP method

POST

Response

None


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /resetroleinheritance
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

ValidateUpdateListItem method

Validates and sets the values of the specified collection of fields for the list item.

Endpoint

/validateupdatelistitem

Parameters

formValues

Type: SP.ListItemFormUpdateValue[]
The fields to change and their new values. Pass this parameter in the request body, as shown in the request example.

bNewDocumentUpdate

Type: Boolean
true if the list item is a document being updated after upload; otherwise false. Pass this parameter in the request body, as shown in the request example, or in the URI path.

HTTP method

POST

Response

Type: SP.ListItemFormUpdateValue[]
An array of objects that represent the changed fields and values.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /validateupdatelistitem
    ?@target='<host web url>'",
  method: "POST",
  body: "{ 'formValues':[{'FieldName':'Status', 'FieldValue':'Deferred'},
    {'FieldName':'StartDate', 'FieldValue':'12/31/2014'}], 'bNewDocumentUpdate': false }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json;odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});


  Response example

{"d":{
  "ValidateUpdateListItem":{"results":[
    {
      "__metadata":{"type":"SP.ListItemFormUpdateValue"},
      "ErrorMessage":null,
      "FieldName":"Status",
      "FieldValue":"Deferred",
      "HasException":false
    },{
      "__metadata":{"type":"SP.ListItemFormUpdateValue"},
      "ErrorMessage":null,
      "FieldName":"StartDate",
      "FieldValue":"12/31/2014",
      "HasException":false
    }
  ]}
}}

OData representation

The following example represents an ListItem resource in JSON format. The resource also returns its field values.

{"d":{
  "__metadata":{,
    "id":"2bbdaee6-1172-4e36-9f90-ce35ec9b6207",
    "uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)",
    "etag":"\"1\"",
    "type":"SP.Data.Team_x0020_tasksListItem"
  },
  "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FirstUniqueAncestorSecurableObject"}},
  "RoleAssignments":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/RoleAssignments"}},
  "AttachmentFiles":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/AttachmentFiles"}},
  "ContentType":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/ContentType"}},
  "FieldValuesAsHtml":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesAsHtml"}},
  "FieldValuesAsText":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesAsText"}},
  "FieldValuesForEdit":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesForEdit"}},
  "File":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/File"}},
  "Folder":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/Folder"}},
  "ParentList":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/ParentList"}},
  "FileSystemObjectType":0,
  "Id":2,
  "ID":2,
  "ContentTypeId":"0x0108004F8963A897E4E64A83E990C1B6B65770",
  "Title":"Assign teams",
  "Modified":"2013-09-03T17:50:30Z",
  "Created":"2013-09-03T17:50:30Z",
  "AuthorId":1073741823,
  "EditorId":1073741823,
  "OData__UIVersionString":"1.0",
  "Attachments":false,
  "GUID":"ce6e516e-2da4-4a3e-9325-daf7d7f61490",
  "PredecessorsId":{"results":[1]},
  "Priority":"(2) Normal",
  "Status":"Not Started",
  "PercentComplete":0,
  "AssignedToId":{"results":[1]},
  "Body":null,
  "StartDate":"2014-01-02T08:00:00Z",
  "DueDate":"2014-01-02T08:00:00Z",
  "Checkmark":"0",
  "RelatedItems":null
}}

Represents a collection of ListItem resources.

Endpoint URI  |  Methods  |  OData representation

Endpoint URI

http://<site url>/web/lists(guid'<list id>')/items
http://<site url>/web/lists/getbytitle('<list title>')/items

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get all list items

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

You can use OData query operations to filter for particular items (example: …/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/items?$filter=Status eq 'not started'&$select=Title&$top=5).

POST request example: Create a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.Data.Team_x0020_tasksListItem' },
    'Title': 'Teams incorporate feedback', 'AssignedToId': {"results":[1]},
    'StartDate':'2014-01-29T08:00:00Z', 'DueDate':'2014-01-31T08:00:00Z',
    'PredecessorsId': {"results":[4]} }",
  headers: { 
    "accept": "application/json;odata=verbose",
    "content-type": "application/json;odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});
NoteNote

To create or change a list item, you must know the ListItemEntityTypeFullName property of the list and pass that as the value of type in the HTTP request body.

See ListItem request examples for examples that show how to change or delete a list item.

ListItemCollection methods

GetById

GetById method

Returns the list item with the specified list item identifier.

Endpoint

/getbyid(<item id>)

Parameters

Type: Int32
The ID of the list item.

HTTP method

GET

Response

Type: SP.ListItem
The list item with the specified ID.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items
    /getbyid(2)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or you can just specify the list item ID on the ListItemCollection resource. Example: …/_api/web/lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)

OData representation

The following example represents an ListItemCollection resource in JSON format, which returns a collection of ListItem resources.

{"d":{
  "results":[{
    "__metadata":{
      "id":"dd9ab60c-4653-4654-85de-1d090f0d416f",
      "uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)",
      "etag":"\"1\"",
      "type":"SP.Data.Team_x0020_tasksListItem"
    },
    "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/FirstUniqueAncestorSecurableObject"}},
    "RoleAssignments":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/RoleAssignments"}},
    "AttachmentFiles":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/AttachmentFiles"}},
    "ContentType":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/ContentType"}},
    "FieldValuesAsHtml":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/FieldValuesAsHtml"}},
    "FieldValuesAsText":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/FieldValuesAsText"}},
    "FieldValuesForEdit":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/FieldValuesForEdit"}},
    "File":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/File"}},
    "Folder":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/Folder"}},
    "ParentList":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/ParentList"}},
    "FileSystemObjectType":0,
    "Id":1,
    "ID":1,
    "ContentTypeId":"0x0108004F8963A897E4E64A83E990C1B6B65770",
    "Title":"Triage requests",
    "Modified":"2013-09-03T17:49:26Z",
    "Created":"2013-09-03T17:49:26Z",
    "AuthorId":1073741823,
    "EditorId":1073741823,
    "OData__UIVersionString":"1.0",
    "Attachments":false,
    "GUID":"e132ef1b-698e-4d21-ba1b-29fa5c38fe8e",
    "PredecessorsId":{"results":[]},
    "Priority":"(2) Normal",
    "Status":"Not Started",
    "PercentComplete":0,
    "AssignedToId":{"results":[1,21]},
    "Body":null,
    "StartDate":"2014-01-01T08:00:00Z",
    "DueDate":"2014-01-02T08:00:00Z",
    "Checkmark":"0",
    "RelatedItems":null
    },{
    "__metadata":{
      "id":"687e63a4-ed44-4bf2-881f-c83e5d3fd020",
      "uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)",
      "etag":"\"5\"",
      "type":"SP.Data.Team_x0020_tasksListItem"
    },
    "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FirstUniqueAncestorSecurableObject"}},
    "RoleAssignments":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/RoleAssignments"}},
    "AttachmentFiles":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/AttachmentFiles"}},
    "ContentType":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/ContentType"}},
    "FieldValuesAsHtml":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesAsHtml"}},
    "FieldValuesAsText":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesAsText"}},
    "FieldValuesForEdit":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesForEdit"}},
    "File":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/File"}},
    "Folder":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/Folder"}},
    "ParentList":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/ParentList"}},
    "FileSystemObjectType":0,
    "Id":2,
    "ID":2,
    "ContentTypeId":"0x0108004F8963A897E4E64A83E990C1B6B65770",
    "Title":"Assign teams",
    "Modified":"2013-09-03T19:24:51Z",
    "Created":"2013-09-03T17:50:30Z",
    "AuthorId":1073741823,
    "EditorId":1073741823,
    "OData__UIVersionString":"1.0",
    "Attachments":false,
    "GUID":"ce6e516e-2da4-4a3e-9325-daf7d7f61490",
    "PredecessorsId":{"results":[1]},
    "Priority":"(1) High",
    "Status":"In Progress",
    "PercentComplete":0.3,
    "AssignedToId":{"results":[1]},
    "Body":null,
    "StartDate":"2014-01-02T08:00:00Z",
    "DueDate":"2014-01-02T08:00:00Z",
    "Checkmark":"0",
    "RelatedItems":null
    },{
    …
  }]
}}

Specifies a list view.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/lists(guid'<list id>')/views('<view id>')

Supported HTTP methods

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Request examples

GET request example: Get a view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can use the GetByTitle method from the ViewCollection resource to get a view by its (case-sensitive) title. Example: …/web/lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views/getbytitle('By Status').

MERGE request example: Change a view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.View' }, 'Title': 'New Mobile Default View',
    'MobileDefaultView': true, 'RowLimit': 5 }",
  headers: { 
    "content-type": "application/json;odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

DELETE request example: Delete a view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

To create a view, see ViewCollection request examples.

View 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
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')/<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

Aggregations

String

RW

Yes

Gets or sets a value that specifies fields and functions that define totals shown in a list view. If not null, the XML must conform to FieldRefDefinitionAggregation, as specified in [MS-WSSCAML].

AggregationsStatus

String

RW

Yes

Gets or sets a value that specifies whether totals are shown in the list view.

BaseViewId

String

R

Yes

Gets a value that specifies the base view identifier of the list view.

ContentTypeId

SP.ContentTypeId

RW

Yes

Gets or sets the identifier of the content type with which the view is associated so that the view is available only on folders of this content type.

DefaultView

Boolean

RW

Yes

Gets or sets a value that specifies whether the list view is the default list view.

DefaultViewForContentType

Boolean

RW

Yes

Gets or sets a value that specifies whether the list view is the default list view for the content type specified by contentTypeId.

EditorModified

Boolean

RW

Yes

Gets or sets a value that specifies whether the list view was modified in an editor.

Formats

String

RW

Yes

Gets or sets a value that specifies the column and row formatting for the list view. If not null, the XML must conform to ViewFormatDefinitions, as specified in [MS-WSSCAML].

Hidden

Boolean

RW

Yes

Gets or sets a value that specifies whether the list view is hidden.

HtmlSchemaXml

String

R

Yes

Gets a value that specifies the XML document that represents the list view.

Id

GUID

R

Yes

Gets a value that specifies the view identifier of the list view.

ImageUrl

String

R

Yes

Gets a value that specifies the URI (Uniform Resource Identifier) of the image for the list view.

IncludeRootFolder

Boolean

RW

Yes

Gets or sets a value that specifies whether the current folder is displayed in the list view.

JsLink

String

RW

Yes

Gets or sets the name of the JavaScript file used for the view.

ListViewXml

String

RW

Yes

Gets or sets a string that represents the view XML.

Method

String

RW

Yes

Gets or sets a value that specifies the view method for the list view. If not null, the XML must conform to Method, as specified in [MS-WSSCAP].

MobileDefaultView

Boolean

RW

Yes

Gets or sets a value that specifies whether the list view is the default mobile list view.

MobileView

Boolean

RW

Yes

Gets or sets a value that specifies whether the list view is a mobile list view.

ModerationType

String

R

Yes

Gets a value that specifies the content approval type for the list view.

OrderedView

Boolean

R

Yes

Gets a value that specifies whether list items can be reordered in the list view.

Paged

Boolean

RW

Yes

Gets or sets a value that specifies whether the list view is a paged view.

PersonalView

Boolean

R

Yes

Gets a value that specifies whether the list view is a personal view.

ReadOnlyView

Boolean

R

Yes

Gets a value that specifies whether the list view is read-only.

RequiresClientIntegration

Boolean

R

Yes

Gets a value that specifies whether the list view requires client integration rights.

RowLimit

Int32

RW

Yes

Gets or sets a value that specifies the maximum number of list items to display in a visual page of the list view.

Scope

Int32

RW

Yes

Gets or sets a value that specifies the scope for the list view. Represents a ViewScope value. DefaultValue = 0, Recursive = 1, RecursiveAll = 2, FilesOnly = 3.

ServerRelativeUrl

String

R

Yes

Gets a value that specifies the server-relative URL of the list view page.

StyleId

String

R

Yes

Gets a value that specifies the identifier of the view style for the list view.

Threaded

Boolean

R

Yes

Gets a value that specifies whether the list view is a threaded view.

Title

String

RW

Yes

Gets or sets a value that specifies the display name of the list view.

Toolbar

String

RW

Yes

Gets or sets a value that specifies the toolbar for the list view.

ToolbarTemplateName

String

R

Yes

Gets a value that specifies the name of the template for the toolbar that is used in the list view.

ViewData

String

RW

Yes

Gets or sets a value that specifies the view data for the list view. If not null, the XML must conform to FieldRefDefinitionViewData, as specified in [MS-WSSCAML].

ViewFields

SP.ViewFieldCollection

R

No

Gets a value that specifies the collection of fields in the list view.

ViewJoins

String

RW

Yes

Gets or sets a value that specifies the joins that are used in the list view. If not null, the XML must conform to ListJoinsDefinition, as specified in [MS-WSSCAML].

ViewProjectedFields

String

RW

Yes

Gets or sets a value that specifies the projected fields that will be used by the list view. If not null, the XML must conform to ProjectedFieldsDefinitionType, as specified in [MS-WSSCAML].

ViewQuery

String

RW

Yes

Gets or sets a value that specifies the query that is used by the list view. If not null, the XML must conform to CamlQueryRoot, as specified in [MS-WSSCAML].

ViewType

String

R

Yes

Gets a value that specifies the type of the list view. Can be HTML, GRID, CALENDAR, RECURRENCE, CHART, or GANTT.

View methods

DeleteObject
RenderAsHtml

DeleteObject method

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

RenderAsHtml method

Returns the list view as HTML.

Endpoint

/renderashtml

Parameters

None

HTTP method

GET

Response

Type: String
The list view rendered in HTML format.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    /renderashtml
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a View resource in JSON format.

{"d":{
  "__metadata":{,
    "id":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
    "uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
    "type":"SP.View"
  },
  "ViewFields":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')/ViewFields"}},
  "Aggregations":null,
  "AggregationsStatus":null,
  "BaseViewId":"2",
  "ContentTypeId":{"__metadata":{"type":"SP.ContentTypeId"}, "StringValue":"0x"},
  "DefaultView":false,
  "DefaultViewForContentType":false,
  "EditorModified":false,
  "Formats":null,
  "Hidden":false,
  "HtmlSchemaXml":"<View Name=\"{0DC42244-4BAE-4DA9-B074-8B8E9D8E50BC}\" MobileView=\"TRUE\" Type=\"HTML\" DisplayName=\"Late Tasks\" Url=\"/Lists/Backlog items/late.aspx\" Level=\"1\" BaseViewID=\"2\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\"><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><RowLimit Paged=\"TRUE\">100</RowLimit><Toolbar Type=\"Standard\" /><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /></ViewFields><ViewData><FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" /></ViewData><Query><Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy></Query></View>",
  "Id":"0dc42244-4bae-4da9-b074-8b8e9d8e50bc",
  "ImageUrl":"/_layouts/15/images/issuelst.png?rev=31",
  "IncludeRootFolder":false,
  "ViewJoins":null,
  "JSLink":"hierarchytaskslist.js",
  "ListViewXml":"<View Name=\"{0DC42244-4BAE-4DA9-B074-8B8E9D8E50BC}\" MobileView=\"TRUE\" Type=\"HTML\" DisplayName=\"Late Tasks\" Url=\"/Lists/Backlog items/late.aspx\" Level=\"1\" BaseViewID=\"2\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\" ><Query><Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy></Query><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /></ViewFields><RowLimit Paged=\"TRUE\">100</RowLimit><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><Toolbar Type=\"Standard\"/></View>",
  "Method":null,
  "MobileDefaultView":false,
  "MobileView":true,
  "ModerationType":null,
  "OrderedView":false,
  "Paged":true,
  "PersonalView":false,
  "ViewProjectedFields":null,
  "ViewQuery":"<Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy>",
  "ReadOnlyView":false,
  "RequiresClientIntegration":false,
  "RowLimit":100,
  "Scope":0,
  "ServerRelativeUrl":"/Lists/Backlog items/late.aspx",
  "StyleId":null,
  "Threaded":false,
  "Title":"Late Tasks",
  "Toolbar":"",
  "ToolbarTemplateName":null,
  "ViewType":"HTML",
  "ViewData":"<FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" />"
}}

Represents a collection of View resources.

Endpoint URI  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/lists(guid'<list id>')/views

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get all views for a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a specific view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can use the GetByTitle method from the ViewCollection resource to get a view by its (case-sensitive) title. Example: …/web/lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views/getbytitle('By Status').

POST request example: Create a view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.View' }, 'Title': 'By Status',
    'PersonalView': false }",
  headers: { 
    "accept": "application/json;odata=verbose",
    "content-type": "application/json;odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

When you create a view, the server returns the view. To add, remove, or change the order of view fields for the new view, use the ViewFieldCollection methods.

ViewCollection methods

GetById
GetByTitle

GetById method

Gets the list view with the specified ID.

Endpoint

/getbyid('<view id>')

Parameters

Type: String
The ID of the view.

HTTP method

GET

Response

Type: SP.View
The specified view.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views
    /getbyid('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can just pass the view ID to the ViewCollection resource. Example: …/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc').

GetByTitle method

Gets the list view with the specified title.

Endpoint

/getbytitle('<view title>')

Parameters

Type: String
The case-sensitive title of the view.

HTTP method

GET

Response

Type: SP.View
The specified view.


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views
    /getbytitle('By Status')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a ViewCollection resource in JSON format.

{"d":{
  "results":[{
    "__metadata":{
      "id":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
      "uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
      "type":"SP.View"
    },
    "ViewFields":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')/ViewFields"}},
    "Aggregations":null,
    "AggregationsStatus":null,
    "BaseViewId":"1",
    "ContentTypeId":{"__metadata":{"type":"SP.ContentTypeId"},"StringValue":"0x"},
    "DefaultView":true,
    "DefaultViewForContentType":false,
    "EditorModified":false,
    "Formats":null,
    "Hidden":false,
    "HtmlSchemaXml":"<View Name=\"{9824C4FF-14FD-4F24-B481-FA33D90F2D85}\" DefaultView=\"TRUE\" MobileView=\"TRUE\" MobileDefaultView=\"TRUE\" Type=\"HTML\" DisplayName=\"All Tasks\" Url=\"/Lists/Backlog items/AllItems.aspx\" Level=\"1\" BaseViewID=\"1\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\"><Toolbar Type=\"Standard\" /><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /><FieldRef Name=\"Status0\" /></ViewFields><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><RowLimit Paged=\"TRUE\">100</RowLimit><ViewData><FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" /></ViewData></View>"
    "Id":"9824c4ff-14fd-4f24-b481-fa33d90f2d85",
    "ImageUrl":"/_layouts/15/images/issuelst.png?rev=31",
    "IncludeRootFolder":false,
    "ViewJoins":null,
    "JSLink":"hierarchytaskslist.js",
    "ListViewXml":"<View Name=\"{9824C4FF-14FD-4F24-B481-FA33D90F2D85}\" DefaultView=\"TRUE\" MobileView=\"TRUE\" MobileDefaultView=\"TRUE\" Type=\"HTML\" DisplayName=\"All Tasks\" Url=\"/Lists/Backlog items/AllItems.aspx\" Level=\"1\" BaseViewID=\"1\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\" ><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /><FieldRef Name=\"Status0\" /></ViewFields><RowLimit Paged=\"TRUE\">100</RowLimit><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><Toolbar Type=\"Standard\"/></View>",
    "Method":null,
    "MobileDefaultView":true,
    "MobileView":true,
    "ModerationType":null,
    "OrderedView":false,
    "Paged":true,
    "PersonalView":false,
    "ViewProjectedFields":null,
    "ViewQuery":null
    "ReadOnlyView":false,
    "RequiresClientIntegration":false,
    "RowLimit":100,
    "Scope":0,
    "ServerRelativeUrl":"/Lists/Backlog items/AllItems.aspx",
    "StyleId":null,
    "Threaded":false,
    "Title":"All Tasks",
    "Toolbar":"",
    "ToolbarTemplateName":null,
    "ViewType":"HTML",
    "ViewData":"<FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" />"}}"
  },{
    "__metadata":{
      "id":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
      "uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
      "type":"SP.View"
    },
    "ViewFields":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')/ViewFields"}},
    "Aggregations":null,
    "AggregationsStatus":null,
    "BaseViewId":"2",
    "ContentTypeId":{"__metadata":{"type":"SP.ContentTypeId"},"StringValue":"0x"},
    "DefaultView":false,
    "DefaultViewForContentType":false,
    "EditorModified":false,
    "Formats":null,
    "Hidden":false,
    "HtmlSchemaXml":"<View Name=\"{0DC42244-4BAE-4DA9-B074-8B8E9D8E50BC}\" MobileView=\"TRUE\" Type=\"HTML\" DisplayName=\"Late Tasks\" Url=\"/Lists/Backlog items/late.aspx\" Level=\"1\" BaseViewID=\"2\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\"><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><RowLimit Paged=\"TRUE\">100</RowLimit><Toolbar Type=\"Standard\" /><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /></ViewFields><ViewData><FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" /></ViewData><Query><Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy></Query></View>",
    "Id":"0dc42244-4bae-4da9-b074-8b8e9d8e50bc",
    "ImageUrl":"/_layouts/15/images/issuelst.png?rev=31",
    "IncludeRootFolder":false,
    "ViewJoins":null,
    "JSLink":"hierarchytaskslist.js",
    "ListViewXml":"<View Name=\"{0DC42244-4BAE-4DA9-B074-8B8E9D8E50BC}\" MobileView=\"TRUE\" Type=\"HTML\" DisplayName=\"Late Tasks\" Url=\"/Lists/Backlog items/late.aspx\" Level=\"1\" BaseViewID=\"2\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\" ><Query><Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy></Query><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /></ViewFields><RowLimit Paged=\"TRUE\">100</RowLimit><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><Toolbar Type=\"Standard\"/></View>",
    "Method":null,
    "MobileDefaultView":false,
    "MobileView":true,
    "ModerationType":null,
    "OrderedView":false,
    "Paged":true,
    "PersonalView":false,
    "ViewProjectedFields":null,
    "ViewQuery":"<Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy>",
    "ReadOnlyView":false,
    "RequiresClientIntegration":false,
    "RowLimit":100,
    "Scope":0,
    "ServerRelativeUrl":"/Lists/Backlog items/late.aspx",
    "StyleId":null,
    "Threaded":false,
    "Title":"Late Tasks",
    "Toolbar":"",
    "ToolbarTemplateName":null,
    "ViewType":"HTML",
    "ViewData":"<FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" />"
  },{
    …
  }]
}}

Represents a collection of fields in a list view.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/lists(guid'<list id>')/views('<view id>')/viewfields

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get all the fields in a view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ViewFieldCollection 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
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields/schemaxml
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property

Type

R/W

Returned with resource

Description

SchemaXml

String

R

Yes

Gets a value that specifies the XML schema that represents the collection.

Items

Collection(String)

R

Yes

Specifies the XML schema of the collection of fields. The Items property is returned with the resource, but it doesn't have a URI-addressable endpoint.

ViewFieldCollection methods

AddViewField
MoveViewFieldTo
RemoveAllViewFields
RemoveViewField

AddViewField method

Adds the field with the specified field internal name or display name to the collection.

Endpoint

/addviewfield('<field name>')

Parameters

Type: String
The case-sensitive internal name or display name of the field to add.

HTTP method

POST

Response

None


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields
    /addviewfield('AssignedTo')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

MoveViewFieldTo method

Moves the field with the specified field internal name to the specified position in the collection.

Endpoint

/moveviewfieldto

Parameters

field

Type: String
The case-sensitive internal name of the field to move. Send this parameter and the index parameter in the request body, as shown in the example.

index

Type: Int32
The zero-based index of the new position for the field. Send this parameter and the field parameter in the request body, as shown in the example.

HTTP method

POST

Response

None


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields
    /moveviewfieldto
    ?@target='<host web url>'",
  method: "POST",
  body: "{ 'field': 'DueDate', 'index': 0 }",
  headers: { "content-type": "application/json;odata=verbose" },
  success: successHandler,
  error: errorHandler
});

RemoveAllViewFields method

Removes all the fields from the collection.

Endpoint

/removeallviewfields

Parameters

None

HTTP method

POST

Response

None


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields
    /removeallviewfields
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

RemoveViewField method

Removes the field with the specified field internal name from the collection.

Endpoint

/removeviewfield('<field name>')

Parameters

Type: String
The case-sensitive internal name of the field to remove from the view.

HTTP method

POST

Response

None


  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields
    /removeviewfield('AssignedTo')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a ViewFieldCollection resource in JSON format.

{"d":{
  "__metadata":{
    "id":"https://<site url>/_api/SP.AppContextSite(@target)/web/lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields",
    "uri":"https://<site url>/_api/SP.AppContextSite(@target)/web/lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields",
    "type":"SP.ViewFieldCollection"
  },
  "SchemaXml":"<FieldRef Name=\"Checkmark\" /><FieldRef Name=\"Status\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" />",
  "Items":{"results":["Checkmark", "Status", "LinkTitle", "DueDate"]}
}}
Show: