Skip to content

driveitem-setretentionlabel.md

Latest commit

 

History

History
148 lines (111 loc) · 5.64 KB

driveitem-setretentionlabel.md

File metadata and controls

148 lines (111 loc) · 5.64 KB
title driveItem: setRetentionLabel
description Apply a retention label on a driveItem asynchronously.
author kyracatwork
ms.localizationpriority medium
ms.subservice onedrive
doc_type apiPageType
ms.date 11/06/2025

driveItem: setRetentionLabel

Namespace: microsoft.graph

Apply (set) a retention label on a driveItem (files and folders). Retention labels don't need to be published in a retention label policy to be applied using this method.

When a retention label is applied to a folder, all the items in the folder are tagged with the same retention label. For information about conflict resolution for retention labels, see Will an existing label be overridden or removed. For information about retention labels from an administrator's perspective, see Use retention labels to manage the lifecycle of documents stored in SharePoint.

[!INCLUDE national-cloud-support]

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

[!INCLUDE permissions-table]

Note

Sites.FullControl.All is the least privileged permission required to change retention labels that classify the content as records.

[!INCLUDE app-permissions]

HTTP request

PATCH /drives/{drive-id}/items/{item-id}/retentionLabel

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.

Request body

In the request body, provide a JSON object with the following parameter.

Property Type Description
name String Specifies the name of the retention label.

Response

When a file is applied with a retention label for the first time, this method returns a 201 Created response code and an updated itemRetentionLabel object in the response body. Subsequent updates to retentionLabel return a 200 OK response code.

Examples

Request

The following example shows a request.

HTTP

PATCH https://graph.microsoft.com/v1.0/drives/b!t18F8ybsHUq1z3LTz8xvZqP8zaSWjkFNhsME-Fepo75dTf9vQKfeRblBZjoSQrd7/items/01NKDM7HMOJTVYMDOSXFDK2QJDXCDI3WUK/retentionLabel
Content-Type: application/json

{
  "name": "Retention label for Contracts"
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "Retention label for Contracts",
  "retentionSettings": {
    "behaviorDuringRetentionPeriod": "retain",
    "isDeleteAllowed": false,
    "isRecordLocked": false,
    "isMetadataUpdateAllowed": false,
    "isContentUpdateAllowed": false,
    "isLabelUpdateAllowed": false
  },
  "isLabelAppliedExplicitly": false,
  "labelAppliedDateTime": "2022-12-22T10:18:23.6580555+00:00",
  "labelAppliedBy": {
    "user": {
      "id": "56d171c8-a92e-4359-9c4a-38b88ac7eabd",
      "displayName": "Contoso Admin"
    }
  }
}