retentionCompliancePolicies

Purview Retention Policies. Microsoft Purview retention policies applied across Microsoft 365 workloads. The retentionCompliancePolicies entity set lives under /exchange/v1.0/retentionCompliancePolicies in the Governance & protection category.

Fact	Value
Path	`/exchange/v1.0/retentionCompliancePolicies`
Category	Governance & protection
Tier	Tier 5, Compliance
Read role	`Compliance.IPPS.Read.All` (Community)
Write role	`Compliance.IPPS.ReadWrite.All` (Enterprise)
Backing cmdlets	Get-RetentionCompliancePolicy, Set-RetentionCompliancePolicy, New-RetentionCompliancePolicy, Remove-RetentionCompliancePolicy

Routes

Method	Path	Synopsis	Role	Plan
GET	`/exchange/v1.0/retentionCompliancePolicies`	List retentionCompliancePolicies entries.	`Compliance.IPPS.Read`	Community
POST	`/exchange/v1.0/retentionCompliancePolicies`	Create a new retentionCompliancePolicies entry. Body keys map 1:1 to New-RetentionCompliancePolicy parameter names (camelCased). Required: name. Returns 201 + Location + the freshly-fetched policy.	`Compliance.IPPS.ReadWrite`	Enterprise
GET	`/exchange/v1.0/retentionCompliancePolicies/{key}`	Get a single retentionCompliancePolicies entry by Identity (Name or GUID).	`Compliance.IPPS.Read`	Community
PATCH	`/exchange/v1.0/retentionCompliancePolicies/{key}`	Partial update of the retentionCompliancePolicies at /retentionCompliancePolicies/{key}. Body keys map 1:1 to Set-RetentionCompliancePolicy parameters. Use Add/Remove location params to add/remove workload locations rather than replacing the whole list. Returns 200 + the post-Set entity.	`Compliance.IPPS.ReadWrite`	Enterprise
DELETE	`/exchange/v1.0/retentionCompliancePolicies/{key}`	Remove the retentionCompliancePolicies at /retentionCompliancePolicies/{key}. Pre-checks DistributionStatus and returns 409 PolicyDistributionPending while the policy is still distributing to workloads (per MS SCC docs - Remove-* fails opaquely in that state). Returns 204 on success.	`Compliance.IPPS.ReadWrite`	Enterprise

GET /exchange/v1.0/retentionCompliancePolicies

List retentionCompliancePolicies entries.

Backing cmdlet: Get-RetentionCompliancePolicy. Role: Compliance.IPPS.Read (Community).

Parameter	In	Type	Description
`distributionDetail`	query	bool (switch)	Include per-location distribution detail. Slower; opt in only when needed.
`retentionRuleTypes`	query	bool (switch)	Return only policies whose rule type matches the requested rule-types filter.
`includeTestModeResults`	query	bool (switch)	Include test-mode (simulation) results.
`teamsPolicyOnly`	query	bool (switch)	Return only Teams-scoped retention policies.
`excludeTeamsPolicy`	query	bool (switch)	Exclude Teams-scoped retention policies from the result.
`errorPolicyOnly`	query	bool (switch)	Return only policies that are in an error state.

List Purview retention compliance policies

Lists tenant-wide Purview retention compliance policies via Get-RetentionCompliancePolicy on the IPPS pool. The IPPS sibling of GET /retentionPolicies (EXO-only); IPPS retention covers a wider workload scope - Exchange, SharePoint, OneDrive, Teams (chat + channel), Yammer. Tier 5 IPPS - backed by Compliance.IPPS.Read.All.

GET /exchange/v1.0/retentionCompliancePolicies HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#retentionCompliancePolicies(Id,Name,Mode,Enabled,Workload,Priority)",
  "value": [
    {
      "Id": "policy-default-7y",
      "Name": "default-7y-retention",
      "Enabled": false,
      "Mode": "Enforce",
      "Workload": "Exchange, SharePoint, OneDriveForBusiness, Skype, ModernGroup, DynamicScope",
      "Priority": 0
    },
    {
      "Id": "policy-finance-keep",
      "Name": "finance-keep-no-delete",
      "Enabled": true,
      "Mode": "Enforce",
      "Workload": "Exchange, SharePoint, OneDriveForBusiness, Skype, ModernGroup, DynamicScope",
      "Priority": 2
    }
  ]
}

POST /exchange/v1.0/retentionCompliancePolicies

Create a new retentionCompliancePolicies entry. Body keys map 1:1 to New-RetentionCompliancePolicy parameter names (camelCased). Required: name. Returns 201 + Location + the freshly-fetched policy.

Creates a Purview retention policy that will distribute asynchronously to one or more workloads (Exchange, SharePoint, OneDrive, Teams, etc.). The cmdlet rejects a name-only body - at least one location parameter must accompany name (typically exchangeLocation: [“All”]) to disambiguate the cmdlet’s parameter sets. The controller passes omitConfirm: true because IPPS-side New-RetentionCompliancePolicy rejects the universally-injected -Confirm:$false. Pass ?dryRun=true to map to -WhatIf.After create, DistributionStatus begins as “Pending”; SCC Remove operations on this policy are blocked until distribution completes. Either wait (typically minutes) or call PATCH with {“retryDistribution”: true} to expedite.

Backing cmdlet: New-RetentionCompliancePolicy. Role: Compliance.IPPS.ReadWrite (Enterprise).

Parameter	In	Type	Required
`name`	body		yes
`adaptiveScopeLocation`	body
`applications`	body
`comment`	body
`enabled`	body
`exchangeLocation`	body
`exchangeLocationException`	body
`isSimulation`	body	boolean (switch)
`modernGroupLocation`	body
`modernGroupLocationException`	body
`oneDriveLocation`	body
`oneDriveLocationException`	body
`policyRBACScopes`	body
`publicFolderLocation`	body
`restrictiveRetention`	body
`sharePointLocation`	body
`sharePointLocationException`	body
`skypeLocation`	body
`teamsChannelLocation`	body
`teamsChannelLocationException`	body
`teamsChatLocation`	body
`teamsChatLocationException`	body
`dryRun`	query	bool (switch)

Create a Purview retention compliance policy

Create a tenant-wide Purview retention policy via New-RetentionCompliancePolicy on the IPPS pool. Required: name. The cmdlet rejects a name-only body - provide at least one location parameter (e.g. exchangeLocation:[“All”]) to disambiguate the parameter set. Set enabled:false during testing for a no-op create that can be safely deleted. Tier 5 IPPS - backed by Compliance.IPPS.ReadWrite.All; the cmdlet ignores -Confirm so the controller omits it.

POST /exchange/v1.0/retentionCompliancePolicies HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "finance-7y-retention",
  "comment": "Retain finance content for 7 years per regulatory requirement.",
  "exchangeLocation": [
    "All"
  ],
  "enabled": true
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/retentionCompliancePolicies/finance-7y-retention

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#retentionCompliancePolicies/$entity",
  "Id": "policy-finance-7y-guid",
  "Name": "finance-7y-retention",
  "Identity": "policy-finance-7y-guid",
  "Enabled": true,
  "Disabled": false,
  "Mode": "Enforce",
  "DistributionStatus": "Pending",
  "Workload": "Exchange, SharePoint, OneDriveForBusiness, Skype, ModernGroup, DynamicScope",
  "Priority": 3,
  "Comment": "Retain finance content for 7 years per regulatory requirement.",
  "ExchangeLocation": [
    "All"
  ]
}

Related: GET /exchange/v1.0/retentionCompliancePolicies/{key}, PATCH /exchange/v1.0/retentionCompliancePolicies/{key}, DELETE /exchange/v1.0/retentionCompliancePolicies/{key}, GET /exchange/v1.0/retentionComplianceRules?policy={policyId}

GET /exchange/v1.0/retentionCompliancePolicies/{key}

Get a single retentionCompliancePolicies entry by Identity (Name or GUID).

Backing cmdlet: Get-RetentionCompliancePolicy. Role: Compliance.IPPS.Read (Community).

Get a retention compliance policy by identity

Returns a single Purview retention compliance policy by its Identity (Name or GUID). Use this to inspect a policy’s workload locations, distribution status, and retention configuration.

GET /exchange/v1.0/retentionCompliancePolicies/{key} HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#retentionCompliancePolicies/$entity",
  "Id": "FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/LiveTest-Block2-1779984080-rpol",
  "Name": "LiveTest-Block2-1779984080-rpol",
  "Identity": "FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/LiveTest-Block2-1779984080-rpol",
  "Enabled": true,
  "Disabled": false,
  "Mode": "Enforce",
  "Workload": "Exchange, SharePoint, OneDriveForBusiness, Skype, ModernGroup, DynamicScope",
  "Priority": 4,
  "DistributionStatus": "Pending",
  "Comment": "",
  "CreatedBy": "",
  "LastModifiedBy": "",
  "ExchangeLocation": [],
  "SharePointLocation": [],
  "OneDriveLocation": [],
  "ModernGroupLocation": [],
  "TeamsChannelLocation": [],
  "TeamsChatLocation": [],
  "PublicFolderLocation": [],
  "WhenCreated": "2026-05-28T19:01:22+03:00",
  "WhenChanged": "2026-05-28T19:01:31+03:00",
  "AdaptiveScopeLocation": [],
  "Applications": [],
  "CompletedLocations": 0,
  "CreationTimeUtc": "2026-05-28T16:01:22.977Z",
  "DistinguishedName": "CN=LiveTest-Block2-1779984080-rpol,CN=Configuration,CN=contoso.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=FFO,DC=extest,DC=microsoft,DC=com",
  "DistributionResults": null,
  "DistributionSyncStatus": "Unknown",
  "EnforcedBy": null,
  "EnforcedTimeUTC": null,
  "ErrorMetadata": null,
  "ExchangeLocationException": [],
  "ExchangeObjectId": "c9a93faf-a295-4c9f-ac8d-c00964207353",
  "ExcludeSPE": false,
  "ExpectedLocations": 0,
  "ExternalIdentity": "",
  "FailedLocations": 0,
  "ForceValidate": false,
  "GlobalListType": "None",
  "Guid": "c9a93faf-a295-4c9f-ac8d-c00964207353",
  "HasRules": false,
  "IsAdaptivePolicy": false,
  "IsSimulation": false,
  "ItemsMatchedDuringTestMode": 0,
  "ItemStatistics": null,
  "LastStatusUpdateTime": null,
  "Locations": "",
  "ModernGroupLocationException": [],
  "ModificationTimeUtc": "2026-05-28T16:01:31.01Z",
  "ObjectVersion": "bfaf5273-bbf0-42ca-ad76-08debcd26236",
  "OneDriveLocationException": [],
  "OrganizationalUnitRoot": "FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com",
  "OrganizationId": "FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration",
  "PolicyApprovalInfo": null,
  "PolicyConstraints": "{\"AdministrativeUnit\":[]}",
  "PolicyRBACScopes": [],
  "PolicyRulesMetaData": "",
  "PolicyTemplateInfo": null,
  "PriorityCleanup": false,
  "ReadOnly": false,
  "RestrictiveRetention": false,
  "RetainCloudAttachment": false,
  "RetentionRuleTypes": [],
  "SharePointLocationException": [],
  "SimulationPolicyVersion": "00000000-0000-0000-0000-000000000000",
  "SkypeLocation": [],
  "SkypeLocationException": [],
  "TeamsChannelLocationException": [],
  "TeamsChatLocationException": [],
  "TeamsPolicy": false,
  "TestModeStatus": null,
  "TestModeVerdict": null,
  "Type": "Hold",
  "UserAdministrativeUnitMembershipMap": null,
  "VersionCleanupState": "Disabled",
  "WhenChangedUTC": "2026-05-28T16:01:31Z",
  "WhenCreatedUTC": "2026-05-28T16:01:22Z"
}

PATCH /exchange/v1.0/retentionCompliancePolicies/{key}

Partial update of the retentionCompliancePolicies at /retentionCompliancePolicies/{key}. Body keys map 1:1 to Set-RetentionCompliancePolicy parameters. Use Add/Remove location params to add/remove workload locations rather than replacing the whole list. Returns 200 + the post-Set entity.**

Use the delta-style location parameters (addExchangeLocation, removeSharePointLocation, etc.) when adjusting workload scope - Set-* on these list-typed properties REPLACES the entire list, which is rarely what callers want. Pass {“retryDistribution”: true} to expedite SCC distribution if a policy is stuck in DistributionStatus: Pending longer than expected.IPPS-side - controller passes omitConfirm: true.

Backing cmdlet: Set-RetentionCompliancePolicy. Role: Compliance.IPPS.ReadWrite (Enterprise).

Parameter	In	Type
`addExchangeLocation`	body
`addExchangeLocationException`	body
`addModernGroupLocation`	body
`addOneDriveLocation`	body
`addPublicFolderLocation`	body
`addSharePointLocation`	body
`addSkypeLocation`	body
`applications`	body
`comment`	body
`enabled`	body
`removeExchangeLocation`	body
`removeExchangeLocationException`	body
`removeModernGroupLocation`	body
`removeOneDriveLocation`	body
`removePublicFolderLocation`	body
`removeSharePointLocation`	body
`removeSkypeLocation`	body
`restrictiveRetention`	body
`retryDistribution`	body	boolean (switch)
`dryRun`	query	bool (switch)

Update a retention compliance policy

Partial update of a Purview retention compliance policy, backed by Set-RetentionCompliancePolicy. Body keys map 1:1 to cmdlet parameters; use the delta-style Add*/Remove* location parameters to adjust workload scope rather than replacing the whole list. Returns the post-Set entity.

PATCH /exchange/v1.0/retentionCompliancePolicies/{key} HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "comment": "Updated retention scope for Exonaut sample policy",
  "enabled": true,
  "addExchangeLocation": "user@contoso.com"
}

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal

{
  "Id": "exonaut-sample-retentionCompliancePolicies",
  "Identity": "exonaut-sample-retentionCompliancePolicies",
  "Name": "exonaut-sample-retentionCompliancePolicies",
  "Comment": "Updated retention scope for Exonaut sample policy",
  "Enabled": true,
  "Mode": "Enforce",
  "ExchangeLocation": [
    "user@contoso.com"
  ],
  "DistributionStatus": "Pending"
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

DELETE /exchange/v1.0/retentionCompliancePolicies/{key}

Remove the retentionCompliancePolicies at /retentionCompliancePolicies/{key}. Pre-checks DistributionStatus and returns 409 PolicyDistributionPending while the policy is still distributing to workloads (per MS SCC docs - Remove- fails opaquely in that state). Returns 204 on success.*

State-machine guard ahead of the cmdlet: a GET-RetentionCompliancePolicy fetch checks DistributionStatus first. While distribution is “Pending”, the SCC backend refuses Remove operations with an opaque “server side error” - this guard converts that into a clear 409 envelope (code: “PolicyDistributionPending”) BEFORE the cmdlet is invoked. MS-recommended remediation: wait until Distribution finishes (typically minutes), or call PATCH on this policy with {“retryDistribution”: true} to expedite. If DistributionStatus is anything other than Pending, falls through to Remove-RetentionCompliancePolicy. IPPS-side - omitConfirm: true.

Backing cmdlet: Remove-RetentionCompliancePolicy. Role: Compliance.IPPS.ReadWrite (Enterprise).

Parameter	In	Type	Required	Description
`forceDeletion`	query	bool (switch)
`dryRun`	query	bool (switch)

Delete a retention compliance policy

Removes a Purview retention compliance policy, backed by Remove-RetentionCompliancePolicy. A state-machine guard first fetches the policy and returns 409 PolicyDistributionPending while DistributionStatus is Pending; otherwise the policy is removed and 204 is returned.

DELETE /exchange/v1.0/retentionCompliancePolicies/{key} HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

HTTP/1.1 204 No Content

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

?dryRun=true previews of any write stay on Community.