retentionComplianceRules

Purview Retention Rules. Define how long Purview retains content and what happens after. The retentionComplianceRules entity set lives under /exchange/v1.0/retentionComplianceRules in the Governance & protection category.

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

Routes

Method	Path	Synopsis	Role	Plan
GET	`/exchange/v1.0/retentionComplianceRules`	List retentionComplianceRules entries.	`Compliance.IPPS.Read`	Community
POST	`/exchange/v1.0/retentionComplianceRules`	POST /retentionComplianceRules - create a rule under a parent retentionCompliancePolicies. Required body fields: policy (Name or GUID); plus EXACTLY ONE of name / applyComplianceTag / publishComplianceTag (parameter-set discriminator enforced by the cmdlet). Returns 201 + Location + the freshly-fetched rule.	`Compliance.IPPS.ReadWrite`	Enterprise
GET	`/exchange/v1.0/retentionComplianceRules/{key}`	Get a single retentionComplianceRules entry by Identity.	`Compliance.IPPS.Read`	Community
PATCH	`/exchange/v1.0/retentionComplianceRules/{key}`	PATCH /retentionComplianceRules/{key} - partial update. Body keys map 1:1 to Set-RetentionComplianceRule parameters. Returns 200 + post-Set rule.	`Compliance.IPPS.ReadWrite`	Enterprise
DELETE	`/exchange/v1.0/retentionComplianceRules/{key}`	DELETE /retentionComplianceRules/{key} - remove a rule. Optional query: ?forceDeletion=true (bypasses tenant-side soft-delete checks) and ?priorityCleanup=true. Returns 204.	`Compliance.IPPS.ReadWrite`	Enterprise

GET /exchange/v1.0/retentionComplianceRules

List retentionComplianceRules entries.

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

Parameter	In	Type	Required	Description
`policy`	query	string		Scope to a specific retention-compliance policy (Name or GUID).

List Purview retention rules

Lists per-policy retention rules via Get-RetentionComplianceRule on the IPPS pool. Each rule scopes content matching and retention duration under its parent retentionCompliancePolicy (Policy field is the GUID back-pointer). Optional ?policy=<name|guid> narrows to one policy’s rules.

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

HTTP/1.1 200 OK

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

POST /exchange/v1.0/retentionComplianceRules

POST /retentionComplianceRules - create a rule under a parent retentionCompliancePolicies. Required body fields: policy (Name or GUID); plus EXACTLY ONE of name / applyComplianceTag / publishComplianceTag (parameter-set discriminator enforced by the cmdlet). Returns 201 + Location + the freshly-fetched rule.

New-RetentionComplianceRule has three parameter sets - pick the right body shape: “Default” - pass name + retention-duration fields.“ComplianceTag” - pass applyComplianceTag instead of name.“PublishComplianceTag” - pass publishComplianceTag. IPPS-side - omitConfirm: true.

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

Parameter	In	Type	Required
`policy`	body		yes
`applyComplianceTag`	body
`comment`	body
`contentContainsSensitiveInformation`	body
`contentMatchQuery`	body
`excludedItemClasses`	body
`expirationDateOption`	body
`irmRiskyUserProfiles`	body
`machineLearningModelIDs`	body
`name`	body
`publishComplianceTag`	body
`retentionComplianceAction`	body
`retentionDuration`	body
`retentionDurationDisplayHint`	body
`dryRun`	query	bool (switch)

Create a retention compliance rule

Provision a rule under a parent retentionCompliancePolicies via New-RetentionComplianceRule on the IPPS pool. New has THREE parameter sets - pick by which fields you send: (a) Default - name + retentionDuration + retentionDurationDisplayHint; (b) ComplianceTag - applyComplianceTag (instead of name) + retention fields; (c) PublishComplianceTag - publishComplianceTag. The cmdlet enforces mutex; sending multiple identifiers yields a parameter-set error. Block 2 omits -Confirm.

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

{
  "name": "Finance-Email-7yr",
  "policy": "Finance-Retention-Policy",
  "retentionDuration": 2555,
  "retentionDurationDisplayHint": "Years",
  "retentionComplianceAction": "Keep",
  "contentMatchQuery": "subject:\"invoice\" OR subject:\"PO\""
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/retentionComplianceRules/Finance-Email-7yr

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#retentionComplianceRules/$entity",
  "Id": "rule-finance-email-7yr",
  "Name": "Finance-Email-7yr",
  "Identity": "rule-finance-email-7yr",
  "Policy": "Finance-Retention-Policy",
  "RetentionDuration": "2555",
  "RetentionDurationDisplayHint": "Years",
  "RetentionComplianceAction": "Keep",
  "ContentMatchQuery": "subject:\"invoice\" OR subject:\"PO\""
}

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

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

Get a single retentionComplianceRules entry by Identity.

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

Get a retention compliance rule by key

Retrieve a single retention compliance rule by its Identity. The rule defines the retention action, duration, and content match scoped to a parent retention compliance policy.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#retentionComplianceRules/$entity",
  "Id": "FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/LiveTest-Block2-1779984080-rrule",
  "Name": "LiveTest-Block2-1779984080-rrule",
  "Identity": "FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/LiveTest-Block2-1779984080-rrule",
  "Policy": "c9a93faf-a295-4c9f-ac8d-c00964207353",
  "Disabled": false,
  "Mode": "Enforce",
  "Workload": "Exchange, SharePoint, OneDriveForBusiness, Skype, ModernGroup, DynamicScope",
  "Priority": 0,
  "RetentionDuration": "30",
  "RetentionDurationDisplayHint": "Days",
  "ExpirationDateOption": "",
  "RetentionComplianceAction": "Keep",
  "ContentMatchQuery": "",
  "Comment": "",
  "WhenCreated": "2026-05-28T19:01:30+03:00",
  "WhenChanged": "2026-05-28T19:01:30+03:00",
  "ApplyComplianceTag": null,
  "ArchiveEnabled": false,
  "ArchiveTriggerBasedOn": "",
  "ArchiveTriggerInDays": null,
  "ComplianceTagProperty": "",
  "ContentContainsSensitiveInformation": null,
  "ContentDateFrom": null,
  "ContentDateTo": null,
  "CreatedBy": "",
  "DistinguishedName": "CN=LiveTest-Block2-1779984080-rrule,CN=Configuration,CN=contoso.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=FFO,DC=extest,DC=microsoft,DC=com",
  "ExchangeObjectId": "d640b3c7-4e50-456f-bcfe-08bcf54f11d7",
  "ExcludedItemClasses": [],
  "ExternalIdentity": "",
  "Guid": "d640b3c7-4e50-456f-bcfe-08bcf54f11d7",
  "ImmutableId": "00000000-0000-0000-0000-000000000000",
  "IRMRiskyUserProfiles": [],
  "LastModifiedBy": "",
  "LogicalWorkload": "None",
  "MachineLearningModelIDs": [],
  "ObjectVersion": "4c311c0a-afef-4aca-1ba3-08debcd2620c",
  "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",
  "PriorityCleanup": false,
  "PublishComplianceTag": "",
  "ReadOnly": false,
  "RetainCloudAttachment": false,
  "WhenChangedUTC": "2026-05-28T16:01:30Z",
  "WhenCreatedUTC": "2026-05-28T16:01:30Z"
}

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

PATCH /retentionComplianceRules/{key} - partial update. Body keys map 1:1 to Set-RetentionComplianceRule parameters. Returns 200 + post-Set rule.

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

Parameter	In	Type
`applyComplianceTag`	body
`comment`	body
`contentContainsSensitiveInformation`	body
`contentDateFrom`	body
`contentDateTo`	body
`contentMatchQuery`	body
`excludedItemClasses`	body
`expirationDateOption`	body
`irmRiskyUserProfiles`	body
`retentionComplianceAction`	body
`retentionDuration`	body
`retentionDurationDisplayHint`	body
`dryRun`	query	bool (switch)

Update a retention compliance rule

Partially update a retention compliance rule by Identity. Body keys map 1:1 to Set-RetentionComplianceRule parameters; only the supplied fields are changed.

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

{
  "comment": "Updated by Exonaut retention automation",
  "retentionDuration": 2555,
  "retentionComplianceAction": "Keep"
}

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

{
  "Identity": "exonaut-sample-retentionComplianceRules",
  "Name": "exonaut-sample-retentionComplianceRules",
  "Comment": "Updated by Exonaut retention automation",
  "RetentionDuration": 2555,
  "RetentionComplianceAction": "Keep"
}

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

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

DELETE /retentionComplianceRules/{key} - remove a rule. Optional query: ?forceDeletion=true (bypasses tenant-side soft-delete checks) and ?priorityCleanup=true. Returns 204.

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

Parameter	In	Type	Description
`dryRun`	query	bool (switch)
`forceDeletion`	query	bool (switch)	Bypass soft-delete checks.
`priorityCleanup`	query	bool (switch)	Mark for priority cleanup.

Delete a retention compliance rule

Remove a retention compliance rule by Identity. Backed by Remove-RetentionComplianceRule. Optional query: ?forceDeletion=true (bypasses tenant-side soft-delete checks) and ?priorityCleanup=true. Returns 204 No Content.

DELETE /exchange/v1.0/retentionComplianceRules/{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.