All our retentionlabel ensure / remove commands currently use the SetComplianceTag endpoint.
However, this method will be deprecated in the near future. This is because of a concern on the boolean parameters that can be used with the endpoints. (See my blog for more information.

We should refactor our commands to use the SetComplianceTagOnBulkItems endpoint, which does not have the same concerns.

An extra reason to switch to using this endpoint is that this endpoint allows you to apply Unpublished retention labels. Which means you can have retention labels that are NOT visible to end users, but usable by automation, which is a real good scenario.

Implementation

The endpoint can be called as follows:

POST <site_url>/_api/SP_CompliancePolicy_SPPolicyStoreProxy_SetComplianceTagOnBulkItems
Authorization: "Bearer <accessToken>"
Content-Type: "application/json"

{
    "listUrl": "<list_absolute_url>",
    "complianceTagValue": "Retain 10 years",
    "itemIds": [1,2,3,4,5]
}

The endpoint returns a 200 response with an "odata.null": true. If a list item cannot be found, it will be returned. The endpoint will also throw an error if the label cannot be found.

An important thing to note is that you'll need the absolute URL of the list, which means we might need to execute an HTTP request to get at it.

Commands to update

• spo listitem retentionlabel ensure/remove
• spo file retentionlabel ensure/remove
• spo folder retentionlabel ensure/remove