What is the term store?
The Term Store in SharePoint Online is a feature used for managing metadata. It allows you to create and manage terms in a hierarchical structure, which can be used across your SharePoint sites to ensure consistent tagging and categorization of content. A term store can be set up tenant wide as well as per site collection.
Within the term store you will find Term sets and Terms:
- Term sets are used to group terms that are related to a specific category or topic
- Terms are individual items within a term set. Each term represents a specific value or keyword that can be used to tag content.
Reading the term store
Getting term sets
A set is the highest level in the term store. It is more like a header for the choices and not selectable by the user.
Method: GET
Uri: _api/v2.1/termStore/groups/TERM STORE GUID/sets
Headers:
{
"Accept": "application/json; odata=verbose",
"Content-Type": "application/json; odata=verbose"
}Getting specific terms with filter
A term is a value, that the user can select from the UI. It has a hierarchy and can down to multiple levels.
Method: GET
Uri: _api/v2.1/termStore/groups/TERM STORE GUID/sets/TERM SET GUID/terms?$filter=id eq 'TERM GUID'
Headers:
{
"Accept": "application/json; odata=verbose",
"Content-Type": "application/json; odata=verbose"
}Getting terms (level 1)
Method: GET
Uri: _api/v2.1/termStore/groups/TERM STORE GUID/sets/TERM SET GUID/terms
Headers:
{
"Accept": "application/json; odata=verbose",
"Content-Type": "application/json; odata=verbose"
}Getting terms (level 2)
Method: GET
Uri: _api/v2.1/termStore/groups/TERM STORE GUID/sets/TERM SET GUID/terms/TERM GUID/terms
Headers:
{
"Accept": "application/json; odata=verbose",
"Content-Type": "application/json; odata=verbose"
}Creating Terms
Each term inside the term store will has a display name, optional synonyms and an optional description. If you need to add multiple languages with each their own properties, adjust the body JSON.
Method: POST
Uri: _api/v2.1/termStore/groups/TERM STORE GUID/sets/TERM SET GUID/children
Headers:
{
"Accept": "application/json; odata=verbose",
"Content-Type": "application/json; odata=verbose"
}
Body: {
"labels": [
{
"name": "DISPLAYNAME",
"isDefault": true,
"languageTag": "en-US"
},
{
"name": "SYNONYM NAME",
"isDefault": false,
"languageTag": "en-US"
}
],
"descriptions": [
{
"description": "DESCRIPTION TEXT",
"languageTag": "en-US"
}
]
}Update Terms
The body is the same to update, make sure you change the URL and your method.
Method: PATCH
Uri: _api/v2.1/termStore/groups/TERM STORE GUID/sets/TERM SET GUID/terms/TERM GUID
Headers:
{
"Accept": "application/json; odata=verbose",
"Content-Type": "application/json; odata=verbose"
}
Body: {
"labels": [
{
"name": "DISPLAYNAME",
"isDefault": true,
"languageTag": "en-US"
},
{
"name": "SYNONYM NAME",
"isDefault": false,
"languageTag": "en-US"
}
],
"descriptions": [
{
"description": "DESCRIPTION TEXT",
"languageTag": "en-US"
}
]
}Update Terms - Available for Tagging
Tagging is usually set to true, since you want to use your term with your documents. If you want to disable your term before you delete it, you can set the tagging to false. It will appear greyed out. If you decide to delete your term directly, the term will also be removed from all documents. To reactivate a term, simply set the isAvailable property to true.
Method: PATCH
Uri: _api/v2.1/termStore/groups/TERM STORE GUID/sets/TERM SET GUID/terms/TERM GUID
Headers:
{
"Accept": "application/json; odata=verbose",
"Content-Type": "application/json; odata=verbose"
}
Body: {
"isAvailableForTagging": [
{
"setId": "PARENT SET ID",
"isAvailable": false
}
]
}