labelPolicies

Sensitivity Label Policies. Publish sensitivity labels to users and locations. The labelPolicies entity set lives under /exchange/v1.0/labelPolicies in the Governance & protection category.

Fact	Value
Path	/exchange/v1.0/labelPolicies
Category	Governance & protection
Tier	Tier 5, Compliance
Read role	Compliance.IPPS.Read.All (Community)
Write role	none (read-only)
Backing cmdlets	Get-LabelPolicy, Set-LabelPolicy, New-LabelPolicy, Remove-LabelPolicy

Routes

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

GET /exchange/v1.0/labelPolicies

List labelPolicies entries.

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

List sensitivity-label publishing policies

Lists sensitivity-label publishing policies via Get-LabelPolicy on the IPPS pool. Each policy determines which users/groups see which labels - the Labels field is the list of label GUIDs the policy publishes; ExchangeLocation/SharePointLocation/OneDriveLocation/ModernGroupLocation scope the audience.

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

HTTP/1.1 200 OK

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#labelPolicies(Id,Name,Mode,Enabled,Workload)",
  "value": [
    {
      "Id": "policy-global-sensitivity",
      "Name": "Global sensitivity label policy",
      "Enabled": true,
      "Mode": "Enforce",
      "Workload": "Exchange, SharePoint, OneDriveForBusiness, Skype, ModernGroup, Applications"
    },
    {
      "Id": "policy-finance-labels",
      "Name": "Finance Label - Policy",
      "Enabled": true,
      "Mode": "Enforce",
      "Workload": "Exchange, SharePoint, OneDriveForBusiness, Skype, ModernGroup, Applications"
    }
  ]
}

Related: GET /exchange/v1.0/labelPolicies/{key}, GET /exchange/v1.0/labels

POST /exchange/v1.0/labelPolicies

Create a new labelPolicies entry. Body keys map 1:1 to New-LabelPolicy parameter names (camelCased). Required: name + labels (list of label GUIDs). Returns 201 + Location + the freshly-fetched policy.

Creates a publishing policy that scopes one or more sensitivity labels to specific users / groups across workloads. labels is a list of label GUIDs (NOT display names - use GET /labels to resolve the Guid). At least one location parameter must accompany the body (typically exchangeLocation: [“All”]) so the cmdlet’s parameter sets can disambiguate. After create, DistributionStatus begins as “Pending”; DELETE on this policy is blocked until distribution finishes. Either wait (typically minutes) or call PATCH with {“retryDistribution”: true} to expedite.IPPS-side - controller passes omitConfirm: true. Pass ?dryRun=true to map to -WhatIf.

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

Parameter	In	Type	Required	Description
labels	body		yes
name	body		yes
advancedSettings	body
comment	body
exchangeAdaptiveScopes	body
exchangeAdaptiveScopesException	body
exchangeLocation	body
exchangeLocationException	body
modernGroupLocation	body
oneDriveLocation	body
policyRBACScopes	body
sharePointLocation	body
dryRun	query	bool (switch)

Create a sensitivity label publishing policy

Create a new label publishing policy via New-LabelPolicy on the IPPS pool. Required: name + labels (list of label GUIDs to publish). At least one location is required - typically exchangeLocation:[“All”] makes the policy publish across all Exchange mailboxes. Tier 5 IPPS - backed by Compliance.IPPS.ReadWrite.All; the cmdlet ignores -Confirm so the controller omits it.

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

{
  "name": "finance-confidentiality",
  "labels": [
    "8faca7b8-8d20-48a3-8ea2-0f96310a848e",
    "1ace2cc3-14bc-4142-9125-bf946a70542c"
  ],
  "comment": "Publishes confidential + internal labels to the finance team.",
  "exchangeLocation": [
    "All"
  ]
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/labelPolicies/finance-confidentiality

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#labelPolicies/$entity",
  "Id": "policy-finance-confidentiality-guid",
  "Name": "finance-confidentiality",
  "Identity": "policy-finance-confidentiality-guid",
  "Enabled": true,
  "Mode": "Enforce",
  "DistributionStatus": "Pending",
  "Workload": "Exchange, SharePoint, OneDriveForBusiness, Skype, ModernGroup, Applications",
  "Labels": [
    "8faca7b8-8d20-48a3-8ea2-0f96310a848e",
    "1ace2cc3-14bc-4142-9125-bf946a70542c"
  ],
  "ExchangeLocation": [
    "All"
  ]
}

Related: GET /exchange/v1.0/labelPolicies, PATCH /exchange/v1.0/labelPolicies/{key}, DELETE /exchange/v1.0/labelPolicies/{key}, GET /exchange/v1.0/labels

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

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

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

Get a sensitivity label policy by identity

Returns a single sensitivity-label publishing policy by its Identity (Name or GUID). The policy determines which published labels appear to which workloads and users, backed by Get-LabelPolicy.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#labelPolicies/$entity",
  "Id": "FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/Global sensitivity label policy",
  "Name": "Global sensitivity label policy",
  "Identity": "FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/Global sensitivity label policy",
  "DisplayName": null,
  "Enabled": true,
  "Mode": "Enforce",
  "Workload": "Exchange, SharePoint, OneDriveForBusiness, Skype, ModernGroup, Applications",
  "Priority": 0,
  "DistributionStatus": "Success",
  "Labels": [
    "defa4170-0d19-0005-0002-bc88714345d2",
    "defa4170-0d19-0005-0000-bc88714345d2",
    "defa4170-0d19-0005-0006-bc88714345d2",
    "defa4170-0d19-0005-000a-bc88714345d2",
    "defa4170-0d19-0005-0003-bc88714345d2",
    "defa4170-0d19-0005-0009-bc88714345d2",
    "defa4170-0d19-0005-0001-bc88714345d2",
    "defa4170-0d19-0005-0007-bc88714345d2",
    "defa4170-0d19-0005-000b-bc88714345d2",
    "defa4170-0d19-0005-0005-bc88714345d2",
    "defa4170-0d19-0005-0004-bc88714345d2",
    "defa4170-0d19-0005-0008-bc88714345d2"
  ],
  "ExchangeLocation": [
    "All"
  ],
  "SharePointLocation": [],
  "OneDriveLocation": [],
  "ModernGroupLocation": [],
  "Comment": "Default sensitivity label policy for all users and groups.",
  "Settings": [
    "[mandatory",
    "false]",
    "[powerbimandatory",
    "false]",
    "[outlookdefaultlabel",
    "defa4170-0d19-0005-0004-bc88714345d2]",
    "[requiredowngradejustification",
    "true]",
    "[defaultlabelid",
    "defa4170-0d19-0005-0004-bc88714345d2]",
    "[disablemandatoryinoutlook",
    "true]"
  ],
  "WhenCreated": "2024-10-24T19:51:22+03:00",
  "WhenChanged": "2024-10-24T19:51:22+03:00",
  "CreatedBy": "",
  "CreationTimeUtc": "2024-10-24T16:51:22.317Z",
  "DistinguishedName": "CN=Global sensitivity label policy,CN=Configuration,CN=contoso.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=FFO,DC=extest,DC=microsoft,DC=com",
  "DistributionResults": null,
  "DistributionSyncStatus": "Success",
  "EndpointDlpAdaptiveScopes": null,
  "EndpointDlpAdaptiveScopesException": null,
  "ErrorMetadata": null,
  "ExchangeAdaptiveScopes": [],
  "ExchangeAdaptiveScopesException": [],
  "ExchangeLocationException": [],
  "ExchangeObjectId": "8b097e7f-3d5c-46c7-8821-4f5d9ff559a2",
  "ExternalIdentity": "",
  "ForceValidate": false,
  "GlobalListType": "None",
  "Guid": "8b097e7f-3d5c-46c7-8821-4f5d9ff559a2",
  "LastModifiedBy": "",
  "LastStatusUpdateTime": "12.06.2025 08:06:19",
  "Locations": "",
  "ModernGroupLocationException": [],
  "ModificationTimeUtc": "2024-10-24T16:51:22.317Z",
  "ObjectVersion": "f1d5bd18-e72d-41df-0731-08dcf44c172b",
  "OneDriveAdaptiveScopes": [],
  "OneDriveAdaptiveScopesException": [],
  "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",
  "PolicyConstraints": "{\"AdministrativeUnit\":[]}",
  "PolicyRBACScopes": [],
  "PolicyRulesMetaData": "",
  "PolicySettingsBlob": "<settings>\r\n  <setting key=\"mandatory\" value=\"false\" />\r\n  <setting key=\"powerbimandatory\" value=\"false\" />\r\n  <setting key=\"outlookdefaultlabel\" value=\"defa4170-0d19-0005-0004-bc88714345d2\" />\r\n  <setting key=\"requiredowngradejustification\" value=\"true\" />\r\n  <setting key=\"defaultlabelid\" value=\"defa4170-0d19-0005-0004-bc88714345d2\" />\r\n  <setting key=\"disablemandatoryinoutlook\" value=\"true\" />\r\n</settings>",
  "PublicFolderLocation": [],
  "ReadOnly": false,
  "ScopedLabels": "defa4170-0d19-0005-0008-bc88714345d2 defa4170-0d19-0005-0007-bc88714345d2 defa4170-0d19-0005-0004-bc88714345d2 defa4170-0d19-0005-0001-bc88714345d2 defa4170-0d19-0005-0003-bc88714345d2 defa4170-0d19-0005-000a-bc88714345d2 defa4170-0d19-0005-0005-bc88714345d2 defa4170-0d19-0005-0002-bc88714345d2 defa4170-0d19-0005-0000-bc88714345d2 defa4170-0d19-0005-0009-bc88714345d2 defa4170-0d19-0005-0006-bc88714345d2 defa4170-0d19-0005-000b-bc88714345d2",
  "SharePointAdaptiveScopes": [],
  "SharePointAdaptiveScopesException": [],
  "SharePointLocationException": [],
  "SkypeLocation": [],
  "SkypeLocationException": [],
  "TeamsAdaptiveScopes": [],
  "TeamsAdaptiveScopesException": [],
  "Type": "PublishedSensitivityLabel",
  "UPELabelRules": "FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-271e3557-a6bf-47c1-837b-5d2a414b3b27 FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-fa7a68dd-665c-4a88-9f1e-ee9f2f8ba22f FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-a2f7e8b5-1c20-4a26-901f-c47368bfc56c FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-8c4df4e8-e75f-4ec2-96d3-2ae752b59de8 FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-6ebeb9b5-e872-4148-aedc-129efe9358e8 FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-351159b9-6ea7-4f07-8c45-9e9ae66393df FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-eb88ae90-b409-48de-98c2-9d2720ecbbbf FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-ed8e617f-d642-461a-b2eb-552a374b7a2e FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-75ce9965-a24c-4479-95c7-6cff47824b2c FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-e549e45d-cefe-4cc2-bd1a-d4d534c061b3 FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-09e2adde-67bc-428e-a72a-e1f048a109a9 FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-1605d63a-ab38-490f-8e5f-b685c3bf1a49 FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-3ef84944-1773-4c99-ac75-a16514fcbd96 FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-3f327c63-f10a-496b-94f9-dc5eac34fb0c FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-353d171f-417e-4155-9623-ae864f44869e FFO.extest.microsoft.com/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com/Configuration/lptr-6845de8b-a67d-43e4-9c0d-98675db6fb3f",
  "UserAdministrativeUnitMembershipMap": null,
  "WhenChangedUTC": "2024-10-24T16:51:22Z",
  "WhenCreatedUTC": "2024-10-24T16:51:22Z"
}

Related: GET /exchange/v1.0/labelPolicies, GET /exchange/v1.0/labels/{key}

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

Partial update of the labelPolicies at /labelPolicies/{key}. Body keys map 1:1 to Set-LabelPolicy parameters. Use Add/Remove params (addLabels, removeLabels, addExchangeLocation, etc.) for delta updates rather than replacing whole lists. Returns 200 + the post-Set policy.**

Use the delta-style list parameters (addLabels / removeLabels, addExchangeLocation / removeSharePointLocation, etc.) when adjusting label set or 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.Label-detach flow: to remove a label from this policy, pass {“removeLabels”: [“{labelGuid}”]} - this is the prerequisite for the LabelInUseByPolicy 409 returned by DELETE /labels/{key}.IPPS-side - controller passes omitConfirm: true.

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

Parameter	In	Type	Required	Description
addExchangeLocation	body
addExchangeLocationException	body
addLabels	body
addModernGroupLocation	body
addOneDriveLocation	body
addSharePointLocation	body
advancedSettings	body
comment	body
nextLabelPolicy	body
policyRBACScopes	body
previousLabelPolicy	body
removeExchangeLocation	body
removeExchangeLocationException	body
removeLabels	body
removeModernGroupLocation	body
removeOneDriveLocation	body
removeSharePointLocation	body
dryRun	query	bool (switch)

Update a sensitivity-label publishing policy

Partial update of a label policy backed by Set-LabelPolicy. Use delta-style list parameters (addLabels/removeLabels, addExchangeLocation/removeExchangeLocation) for label-set and workload-scope adjustments rather than replacing whole lists.

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

{
  "comment": "Updated by Exonaut automation",
  "addExchangeLocation": [
    "All"
  ]
}

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

{
  "Identity": "exonaut-sample-labelPolicies",
  "Name": "exonaut-sample-labelPolicies",
  "Comment": "Updated by Exonaut automation",
  "ExchangeLocation": [
    "All"
  ],
  "DistributionStatus": "Pending"
}

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

Related: GET /exchange/v1.0/labelPolicies

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

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

State-machine guard ahead of the cmdlet: a GET-LabelPolicy 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 for distribution to finish (typically minutes), or call PATCH on this policy with {“retryDistribution”: true} to expedite. If DistributionStatus is anything other than Pending, falls through to Remove-LabelPolicy. IPPS-side - omitConfirm: true.Deleting the policy unblocks any labels it published - see DELETE /labels/{key} and its LabelInUseByPolicy 409 guard.

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

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Delete a sensitivity-label publishing policy

Removes a label policy backed by Remove-LabelPolicy. The controller pre-checks DistributionStatus and returns 409 PolicyDistributionPending while the policy is still distributing to workloads; otherwise the cmdlet runs and 204 No Content is returned.

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

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