autoSensitivityLabelPolicies

Auto-Labeling Policies. Apply sensitivity labels automatically based on content. The autoSensitivityLabelPolicies entity set lives under /exchange/v1.0/autoSensitivityLabelPolicies in the Governance & protection category.

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

Routes

Method	Path	Synopsis	Role	Plan
GET	/exchange/v1.0/autoSensitivityLabelPolicies	List auto-sensitivity label policies - IPPS-backed rules that automatically apply MIP labels based on content matches.	Compliance.IPPS.Read	Community
POST	/exchange/v1.0/autoSensitivityLabelPolicies	POST /autoSensitivityLabelPolicies - create a policy. Required body fields: name + applySensitivityLabel (label GUID). Returns 201 + Location + freshly-fetched policy.	Compliance.IPPS.ReadWrite	Enterprise
GET	/exchange/v1.0/autoSensitivityLabelPolicies/{key}	Get a single auto-sensitivity label policy by Identity. Returns 404 if absent.	Compliance.IPPS.Read	Community
PATCH	/exchange/v1.0/autoSensitivityLabelPolicies/{key}	PATCH /autoSensitivityLabelPolicies/{key} - partial update. Use Add*/Remove* location params for delta updates. Pass {“retryDistribution”: true} to expedite stuck distribution. Returns 200 + post-Set policy.	Compliance.IPPS.ReadWrite	Enterprise
DELETE	/exchange/v1.0/autoSensitivityLabelPolicies/{key}	DELETE /autoSensitivityLabelPolicies/{key} - remove a policy. Pre-checks DistributionStatus (409 PolicyDistributionPending while still distributing). Returns 204.	Compliance.IPPS.ReadWrite	Enterprise

GET /exchange/v1.0/autoSensitivityLabelPolicies

List auto-sensitivity label policies - IPPS-backed rules that automatically apply MIP labels based on content matches.

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

Parameter	In	Type	Required	Description
distributionDetail	query	bool (switch)		Include per-location distribution detail. Slower; opt in only when needed.
includeTestModeResults	query	bool (switch)		Include test-mode (simulation) results.
includeProgressFeedback	query	bool (switch)		Include policy deployment/progress feedback detail.

List auto-labeling policies

Returns the Microsoft Purview auto-sensitivity-labeling policies in the tenant. The value array is empty when no auto-labeling policies have been provisioned.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#autoSensitivityLabelPolicies",
  "value": []
}

Related: GET /exchange/v1.0/autoSensitivityLabelRules

POST /exchange/v1.0/autoSensitivityLabelPolicies

POST /autoSensitivityLabelPolicies - create a policy. Required body fields: name + applySensitivityLabel (label GUID). Returns 201 + Location + freshly-fetched policy.

applySensitivityLabel is the label GUID (not display name) - resolve via GET /labels. At least one workload location is recommended (e.g. exchangeLocation: [“All”]) so the cmdlet’s parameter-set discriminator can resolve. After create, DistributionStatus begins as “Pending”; DELETE is blocked until distribution completes. Either wait or call PATCH with {“retryDistribution”: true} to expedite. IPPS-side - omitConfirm: true.

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

Parameter	In	Type	Required	Description
applySensitivityLabel	body		yes
name	body		yes
comment	body
exceptIfOneDriveSharedBy	body
exceptIfOneDriveSharedByMemberOf	body
exchangeAdaptiveScopes	body
exchangeAdaptiveScopesException	body
exchangeLocation	body
exchangeSender	body
exchangeSenderException	body
exchangeSenderMemberOf	body
exchangeSenderMemberOfException	body
externalMailRightsManagementOwner	body
locations	body
mode	body
oneDriveAdaptiveScopes	body
oneDriveAdaptiveScopesException	body
oneDriveLocation	body
oneDriveLocationException	body
oneDriveSharedBy	body
oneDriveSharedByMemberOf	body
overwriteLabel	body
policyRBACScopes	body
policyTemplateInfo	body
priority	body
sharePointAdaptiveScopes	body
sharePointAdaptiveScopesException	body
sharePointLocation	body
sharePointLocationException	body
unifiedAuditLogEnabled	body
dryRun	query	bool (switch)

Create an auto-labeling policy

Provision a Purview auto-labeling policy via New-AutoSensitivityLabelPolicy on the IPPS pool. Required: name + applySensitivityLabel (label GUID - resolve via GET /labels). At least one workload location is recommended so the cmdlet’s parameter-set discriminator resolves cleanly (here exchangeLocation: [‘All’]). After create, DistributionStatus begins as ‘Pending’; DELETE is blocked until distribution completes. Pass PATCH {“retryDistribution”: true} to expedite if needed.

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

{
  "name": "Auto-Apply-Confidential-Finance",
  "applySensitivityLabel": "8b2a9c7d-1234-5678-9abc-def012345678",
  "comment": "Auto-label financial content reaching finance users.",
  "exchangeLocation": [
    "All"
  ],
  "mode": "TestWithoutNotifications",
  "overwriteLabel": false,
  "priority": 5
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/autoSensitivityLabelPolicies/Auto-Apply-Confidential-Finance

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#autoSensitivityLabelPolicies/$entity",
  "Id": "autopolicy-confidential-finance",
  "Name": "Auto-Apply-Confidential-Finance",
  "Identity": "autopolicy-confidential-finance",
  "Enabled": true,
  "Mode": "TestWithoutNotifications",
  "ApplySensitivityLabel": "8b2a9c7d-1234-5678-9abc-def012345678",
  "ExchangeLocation": [
    "All"
  ],
  "SharePointLocation": [],
  "OneDriveLocation": [],
  "DistributionStatus": "Pending"
}

Related: GET /exchange/v1.0/autoSensitivityLabelPolicies, PATCH /exchange/v1.0/autoSensitivityLabelPolicies/{key}, DELETE /exchange/v1.0/autoSensitivityLabelPolicies/{key}, POST /exchange/v1.0/autoSensitivityLabelRules

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

Get a single auto-sensitivity label policy by Identity. Returns 404 if absent.

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

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

PATCH /autoSensitivityLabelPolicies/{key} - partial update. Use Add/Remove location params for delta updates. Pass {“retryDistribution”: true} to expedite stuck distribution. Returns 200 + post-Set policy.**

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

Parameter	In	Type	Required	Description
addExchangeLocation	body
addOneDriveLocation	body
addOneDriveLocationException	body
addSharePointLocation	body
addSharePointLocationException	body
applySensitivityLabel	body
autoEnableAfter	body
comment	body
enabled	body
exceptIfOneDriveSharedBy	body
exceptIfOneDriveSharedByMemberOf	body
exchangeAdaptiveScopes	body
exchangeAdaptiveScopesException	body
exchangeSender	body
exchangeSenderException	body
exchangeSenderMemberOf	body
exchangeSenderMemberOfException	body
externalMailRightsManagementOwner	body
locations	body
mode	body
oneDriveAdaptiveScopes	body
oneDriveAdaptiveScopesException	body
oneDriveSharedBy	body
oneDriveSharedByMemberOf	body
overwriteLabel	body
policyRBACScopes	body
policyTemplateInfo	body
priority	body
removeExchangeLocation	body
removeOneDriveLocation	body
removeOneDriveLocationException	body
removeSharePointLocation	body
removeSharePointLocationException	body
sharePointAdaptiveScopes	body
sharePointAdaptiveScopesException	body
spoAipIntegrationEnabled	body
startSimulation	body
dryRun	query	bool (switch)

Update an auto-sensitivity label policy

Partially updates a Purview auto-labeling policy by Identity, backed by Set-AutoSensitivityLabelPolicy. Only the fields supplied are changed; returns the post-Set policy.

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

{
  "comment": "Updated by Exonaut automation",
  "enabled": true,
  "priority": 1
}

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

{
  "Identity": "exonaut-sample-autoSensitivityLabelPolicies",
  "Name": "exonaut-sample-autoSensitivityLabelPolicies",
  "Comment": "Updated by Exonaut automation",
  "Enabled": true,
  "Priority": 1,
  "Mode": "Enable",
  "DistributionStatus": "Success"
}

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

Related: GET /exchange/v1.0/autoSensitivityLabelPolicies

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

DELETE /autoSensitivityLabelPolicies/{key} - remove a policy. Pre-checks DistributionStatus (409 PolicyDistributionPending while still distributing). Returns 204.

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

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Delete an auto-sensitivity label policy

Removes a Purview auto-labeling policy by Identity, backed by Remove-AutoSensitivityLabelPolicy. Pre-checks DistributionStatus and returns 409 PolicyDistributionPending while the policy is still distributing; otherwise returns 204.

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

Related: GET /exchange/v1.0/autoSensitivityLabelPolicies

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