SharePoint Online REST APIs (Part II): Lists

Share the love

In the SharePoint Online REST APIs series, I’ll be sharing the most common APIs I use. I mainly use these APIs in Power Automate, so I’ll base the information in this series on the data you need for a Send an HTTP request to SharePoint action.

Similar to the first article, the second article explores how to interact with lists in SharePoint Online. This is not a comprehensive list; rather a list of calls that I use when I can’t use predefined Power Automate actions. I have used the color red to identify interchangeable values.

Get all the lists and libraries in a site

Method

URI

GET

_api/web/lists

Even though the call states list, it will call all the lists and libraries. Technically, a document library is a list too.

Get all the lists in a site

Method

URI

GET

_api/web/lists?$filter=BaseTemplate eq 100

The previous call got all the lists and libraries, but if you want to return lists only, use this call. BaseTemplate refers to list template type. For custom lists, the number is 100. Microsoft has documentation for the other template types.

Get a specific list

Method

URI

GET

_api/web/lists(guid'GUID')/items?$filter=Title eq 'Hello World'

This call will return all the properties of a specific list. Properties can include the list title, description, created date and setting configurations such as allow content types, enable folder creation etc. This call also works for document libraries.

Get a list that starts with a specific word

Method

URI

GET

_api/web/lists?$filter=startswith(Title,'Partial List Name')

Perhaps you want to return all the lists that start with a similar word. Once you have all the list titles, you can loop through all the returned lists to find an item. You can also use a different text column other than Title. Perhaps you want to return all the lists with a similar description etc.

Get a filtered list based on a specific criteria

Method

URI

GET

_api/web/lists(guid'GUID')/items?$filter=Title eq 'Hello World'

Method

URI

GET

_api/web/lists(guid'GUID')/items?$filter=substringof('Hello World'),Title)

This call is useful to find items in a list that meet a specific criteria. I have decided to give two examples here, but any OData filter can work.

Return items of a list that were modified between a specific date range

Method

URI

GET

_api/web/lists(guid'GUID')/items?$select=Title,Modified&$filter=Modified ge '2021-03-14T06:00:02Z' and Modified lt '2021-03-15T06:00:02Z'

Similar to the call above, this call will return items that are modified between a date range. You can also use this call on the Created column or another date column your list has. The date format is is based on the ISO 8601 format. You can also use a date without a time value (it will default to yyyy-MM-dd 00:00:00).

Get the Entity Type Name of a list

Method

URI

GET

_api/web/lists?$select=Title&$filter=EntityTypeName eq 'List Name'

This call finds the Entity Type Name of a specific list. You will need to use the Entity Type Name when programmatically adding an item to a list. Creating a list item is also covered further down in this article.

Get a list view

Method

URI

GET

_api/web/lists(guid'GUID')/Views?$filter=Title eq 'All Items'

This call does not return the items from a specific view (see the above calls for how to filter a list on specific criteria), but rather information about the view itself. You can get properties such as whether the view is the view the default view, internal column names, how the list is sorted etc.

Update list item without affecting the version number

Method

URI

Body

POST

_api/web/lists(guid'GUID')/items(2353)/validateUpdateListItem()

{
"formValues": [
{
"FieldName": "Title",
"FieldValue": "New Title"
},
{
"FieldName": "FileLeafRef",
"FieldValue": "New Filename.ext"
}
],
"bNewDocumentUpdate":true
}

I covered this in the previous article in the series. You can use this call for files and list items.

Filter a list based on a people picker column

Method

URI

GET

_api/web/lists(guid'GUID')/items?$select=PeoplePickerColumnInternalName/EMail&$expand=PeoplePickerColumnInternalName/Id&$filter=ID eq 24

Getting properties of a people picker column requires a little more information. The call above gets the email from the people picker column where the ID of the item is 24. You can also get a myriad of other properties. Below is the list of properties you can select from the people picker field (replace Email from the call above with one of the options below).

NumberProperty
1Id
2ContentTypeID
3ContentType
4Name
5Modified
6Created
7Account
8EMail
9MobileNumber
10AboutMe
11SIPAddress
12IsSiteAdmin
13Deleted
14Hidden
15Picture
16Department
17JobTitle
18LastName
19FirstName

Create a list

Method

URI

Body

POST

_api/web/lists

{
"AllowContentTypes": true,
"BaseTemplate": 100,
"ContentTypesEnabled": true,
"EnableVersioning": true,
"MajorVersionLimit": 1000,
"Description": "A list description",
"Title": "List Title"
}

The call above will create a new list on your site. I have included some optional properties in the Body section. You can specify any properties that are returned with the _api/web/lists call.

Create a new item in a list

Method

URI

Body

POST

_api/web/lists(guid'GUID')/items

{
"Title": "New Title",
"InternalColumnName": "New Value"
}

"__metadata": { "type": "SP.Data.EntityTypeNameItem" }
}

This is where you will need the Entity Type Name of a list. You will need to pass in data of all required columns and any other columns you want to populate.

Change a list title

Method

URI

Headers


Body

POST

_api/web/lists(guid'GUID')

Accept application/json;odata=verbose
Content-Type application/json;odata=verbose
IF-MATCH *
X-HTTP-Method MERGE

{
"__metadata": {
"type": "SP.List"
},
"Title": "New List Title"
}

Surprisingly, changing a list title takes a little more effort than you may think. This call uses merge to update the metadata.

Add a content type to a list

Method

URI

POST

_api/web/lists(guid'GUID')/ContentTypes/AddAvailableContentType('0x0100DCCE177DF386F14C98D57494BDC3983E')

You will need to have already created your Content Type (or use an existing SharePoint Content Type). To get the Content Type ID of the Content Type, go to Site Settings. Click on Site Content Types. Find your Content Type and click into it. You will find your Content Type ID after the ctype= parameter in the browser URL. It should start with 0x01.

Retrieve a content type in a list

Method

URI

GET

_api/web/lists(guid'GUID')/ContentTypes?$filter=Name eq 'Item'

A programmatic way to receive the Content Type ID is searching for the Content Type in another list. In this example we are retrieving the properties of the Item Content Type. This can come in handy when you want to delete the Content Type from a list (see below).

Delete a content type from a list

Method

URI

POST

_api/web/lists(guid'GUID')/ContentTypes('0x0100DCCE177DF386F14C98D57494BDC3983E')/deleteObject()

Finally, we can delete a Content Type from a list. You will need the Content Type ID before using this call.


Share the love

Leave a Reply

Your email address will not be published. Required fields are marked *