labels

Sensitivity Labels. Labels that classify and protect content. The labels entity set lives under /exchange/v1.0/labels in the Governance & protection category.

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

Routes

Method	Path	Synopsis	Role	Plan
GET	`/exchange/v1.0/labels`	List MIP sensitivity labels - the tenant-defined classifications attached to email + files via auto-labeling policies or user pick.	`Compliance.IPPS.Read`	Community
POST	`/exchange/v1.0/labels`	Create a new labels entry. Body keys map 1:1 to New-Label parameter names (camelCased). Required: name + displayName + tooltip. Returns 201 + Location + the freshly-fetched label.	`Compliance.IPPS.ReadWrite`	Enterprise
GET	`/exchange/v1.0/labels/{key}`	Get a single labels entry by Identity (GUID or Name).	`Compliance.IPPS.Read`	Community
PATCH	`/exchange/v1.0/labels/{key}`	Partial update of the labels at /labels/{key}. Body keys map 1:1 to Set-Label parameters. Returns 200 + the post-Set label.	`Compliance.IPPS.ReadWrite`	Enterprise
DELETE	`/exchange/v1.0/labels/{key}`	Remove the labels at /labels/{key}. Pre-checks that no label policy still references this label by its GUID (per MS Purview docs - “You can’t delete a label if it’s still in a label policy”). LabelPolicy.Labels stores GUIDs, NOT display names. Returns 409 LabelInUseByPolicy with the blocking policy names if so. Caller must then detach via PATCH /labelPolicies/{policy} with `{"removeLabels":["{labelGuid}"]}` first. Returns 204 on success.	`Compliance.IPPS.ReadWrite`	Enterprise

GET /exchange/v1.0/labels

List MIP sensitivity labels - the tenant-defined classifications attached to email + files via auto-labeling policies or user pick.

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

Parameter	In	Type	Required	Description
`includeDetailedLabelActions`	query	bool (switch)		Include detailed label-action breakdown (encryption, content marking, watermark, etc.).

List sensitivity labels

Lists Microsoft Information Protection (MIP) sensitivity labels via Get-Label on the IPPS pool. Each label has a GUID-shaped Name, a human-readable DisplayName, optional encryption rights, content marking, and watermark configuration. Add ?includeDetailedLabelActions=true to see the per-label action breakdown (slower).

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

HTTP/1.1 200 OK

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#labels(Id,DisplayName,Mode,Disabled,Priority)",
  "value": [
    {
      "Id": "label-personal-guid",
      "DisplayName": "Personal",
      "Mode": "Enforce",
      "Priority": 0,
      "Disabled": false
    },
    {
      "Id": "label-public-guid",
      "DisplayName": "Public",
      "Mode": "Enforce",
      "Priority": 1,
      "Disabled": false
    },
    {
      "Id": "label-general-guid",
      "DisplayName": "General",
      "Mode": "Enforce",
      "Priority": 2,
      "Disabled": false
    }
  ]
}

POST /exchange/v1.0/labels

Create a new labels entry. Body keys map 1:1 to New-Label parameter names (camelCased). Required: name + displayName + tooltip. Returns 201 + Location + the freshly-fetched label.

Creates a MIP sensitivity label. name is the label’s internal identifier (typically a GUID-shaped string but any unique value works); displayName is what end users see; tooltip is the hover-help text. Optional fields configure content marking (footer/header text + enabled flag), watermark, and encryption rights. Note:priority is Set-Label-only - pass it on PATCH after creation, not in this POST body (the Wiki-drift test enforces this).IPPS-side - controller passes omitConfirm: true. Newly created labels are not yet published - create or extend a labelPolicies entry to make the label visible to users.

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

Parameter	In	Type	Required
`displayName`	body		yes
`name`	body		yes
`tooltip`	body		yes
`advancedSettings`	body
`applyContentMarkingFooterAlignment`	body
`applyContentMarkingFooterEnabled`	body
`applyContentMarkingFooterFontColor`	body
`applyContentMarkingFooterFontName`	body
`applyContentMarkingFooterFontSize`	body
`applyContentMarkingFooterMargin`	body
`applyContentMarkingFooterText`	body
`applyContentMarkingHeaderAlignment`	body
`applyContentMarkingHeaderEnabled`	body
`applyContentMarkingHeaderFontColor`	body
`applyContentMarkingHeaderFontName`	body
`applyContentMarkingHeaderFontSize`	body
`applyContentMarkingHeaderMargin`	body
`applyContentMarkingHeaderText`	body
`applyDynamicWatermarkingEnabled`	body
`applyWaterMarkingEnabled`	body
`applyWaterMarkingFontColor`	body
`applyWaterMarkingFontName`	body
`applyWaterMarkingFontSize`	body
`applyWaterMarkingLayout`	body
`applyWaterMarkingText`	body
`comment`	body
`contentType`	body
`defaultContentLabel`	body
`dynamicWatermarkDisplay`	body
`encryptionAipTemplateScopes`	body
`encryptionContentExpiredOnDateInDaysOrNever`	body
`encryptionDoNotForward`	body
`encryptionDoubleKeyEncryptionUrl`	body
`encryptionEnabled`	body
`encryptionEncryptOnly`	body
`encryptionOfflineAccessDays`	body
`encryptionPromptUser`	body
`encryptionProtectionType`	body
`encryptionRightsDefinitions`	body
`encryptionRightsUrl`	body
`encryptionTemplateId`	body
`labelActions`	body
`localeSettings`	body
`parentId`	body
`siteAndGroupProtectionAllowAccessToGuestUsers`	body
`siteAndGroupProtectionAllowEmailFromGuestUsers`	body
`siteAndGroupProtectionAllowFullAccess`	body
`siteAndGroupProtectionAllowLimitedAccess`	body
`siteAndGroupProtectionBlockAccess`	body
`siteAndGroupProtectionEnabled`	body
`siteAndGroupProtectionPrivacy`	body
`siteExternalSharingControlType`	body
`teamsAllowedPresenters`	body
`teamsAllowMeetingChat`	body
`teamsAllowPrivateTeamsToBeDiscoverableUsingSearch`	body
`teamsBypassLobbyForDialInUsers`	body
`teamsChannelSharedWithExternalTenants`	body
`teamsChannelSharedWithPrivateTeamsOnly`	body
`teamsChannelSharedWithSameLabelOnly`	body
`teamsCopyRestrictionEnforced`	body
`teamsDetectSensitiveContentDuringScreenSharingEnabled`	body
`teamsDisableLobby`	body
`teamsEndToEndEncryptionEnabled`	body
`teamsLobbyBypassScope`	body
`teamsLobbyRestrictionEnforced`	body
`teamsPresentersRestrictionEnforced`	body
`teamsProtectionEnabled`	body
`teamsRecordAutomatically`	body
`teamsVideoWatermark`	body
`teamsWhoCanRecord`	body
`dryRun`	query	bool (switch)

Create a sensitivity label

Create a new MIP sensitivity label via New-Label on the IPPS pool. Required: name (GUID-shaped internal identifier), displayName (human-readable), tooltip. Additional body fields configure content marking + watermark + encryption rights. Tier 5 IPPS - backed by Compliance.IPPS.ReadWrite.All; the cmdlet ignores -Confirm so the controller omits it.

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

{
  "name": "internal-confidential",
  "displayName": "Internal - Confidential",
  "tooltip": "Apply to internal documents not for external distribution.",
  "applyContentMarkingFooterText": "INTERNAL - CONFIDENTIAL",
  "applyContentMarkingFooterEnabled": true
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/labels/internal-confidential

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#labels/$entity",
  "Id": "label-internal-confidential-guid",
  "Name": "internal-confidential",
  "Identity": "label-internal-confidential-guid",
  "DisplayName": "Internal - Confidential",
  "Tooltip": "Apply to internal documents not for external distribution.",
  "Mode": "Enforce",
  "Priority": 14,
  "Disabled": false,
  "ApplyContentMarkingFooterText": "INTERNAL - CONFIDENTIAL"
}

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

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

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

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

Partial update of the labels at /labels/{key}. Body keys map 1:1 to Set-Label parameters. Returns 200 + the post-Set label.

Use this endpoint to adjust label settings post-creation - display name, tooltip, content marking text, encryption rights, watermark, label actions, and (only here, not on POST) priority. IPPS-side - controller passes omitConfirm: true. Changes propagate to users on the next label policy sync; per MS docs, allow up to 24 hours for the full roll-out across apps and services.

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

Parameter	In	Type
`advancedSettings`	body
`applyContentMarkingFooterAlignment`	body
`applyContentMarkingFooterEnabled`	body
`applyContentMarkingFooterFontColor`	body
`applyContentMarkingFooterFontName`	body
`applyContentMarkingFooterFontSize`	body
`applyContentMarkingFooterMargin`	body
`applyContentMarkingFooterText`	body
`applyContentMarkingHeaderAlignment`	body
`applyContentMarkingHeaderEnabled`	body
`applyContentMarkingHeaderFontColor`	body
`applyContentMarkingHeaderFontName`	body
`applyContentMarkingHeaderFontSize`	body
`applyContentMarkingHeaderMargin`	body
`applyContentMarkingHeaderText`	body
`applyDynamicWatermarkingEnabled`	body
`applyWaterMarkingEnabled`	body
`applyWaterMarkingFontColor`	body
`applyWaterMarkingFontName`	body
`applyWaterMarkingFontSize`	body
`applyWaterMarkingLayout`	body
`applyWaterMarkingText`	body
`comment`	body
`conditions`	body
`contentType`	body
`defaultContentLabel`	body
`displayName`	body
`dynamicWatermarkDisplay`	body
`encryptionContentExpiredOnDateInDaysOrNever`	body
`encryptionDoNotForward`	body
`encryptionEnabled`	body
`encryptionEncryptOnly`	body
`encryptionOfflineAccessDays`	body
`encryptionPromptUser`	body
`encryptionProtectionType`	body
`encryptionRightsDefinitions`	body
`encryptionRightsUrl`	body
`labelActions`	body
`localeSettings`	body
`parentId`	body
`priority`	body
`removeParentLink`	body	boolean (switch)
`siteAndGroupProtectionAllowAccessToGuestUsers`	body
`siteAndGroupProtectionAllowEmailFromGuestUsers`	body
`siteAndGroupProtectionAllowFullAccess`	body
`siteAndGroupProtectionAllowLimitedAccess`	body
`siteAndGroupProtectionBlockAccess`	body
`siteAndGroupProtectionEnabled`	body
`siteAndGroupProtectionLevel`	body
`siteAndGroupProtectionPrivacy`	body
`siteExternalSharingControlType`	body
`teamsAllowedPresenters`	body
`teamsAllowMeetingChat`	body
`teamsAllowPrivateTeamsToBeDiscoverableUsingSearch`	body
`teamsBypassLobbyForDialInUsers`	body
`teamsChannelProtectionEnabled`	body
`teamsChannelSharedWithExternalTenants`	body
`teamsChannelSharedWithPrivateTeamsOnly`	body
`teamsChannelSharedWithSameLabelOnly`	body
`teamsCopyRestrictionEnforced`	body
`teamsDetectSensitiveContentDuringScreenSharingEnabled`	body
`teamsDisableLobby`	body
`teamsEndToEndEncryptionEnabled`	body
`teamsLobbyBypassScope`	body
`teamsLobbyRestrictionEnforced`	body
`teamsPresentersRestrictionEnforced`	body
`teamsProtectionEnabled`	body
`teamsRecordAutomatically`	body
`teamsVideoWatermark`	body
`teamsWhoCanRecord`	body
`tooltip`	body
`dryRun`	query	bool (switch)

Update a sensitivity label

Partial update of a MIP sensitivity label. Body keys map 1:1 to Set-Label parameters (camelCased); only fields in the SetWritable allowlist are accepted, including priority which is Set-Label-only.

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

{
  "displayName": "Exonaut Sample Confidential",
  "tooltip": "Use for exonaut-sample content that should stay inside contoso.com.",
  "priority": 3
}

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

{
  "Identity": "exonaut-sample-labels",
  "Name": "exonaut-sample-labels",
  "DisplayName": "Exonaut Sample Confidential",
  "Tooltip": "Use for exonaut-sample content that should stay inside contoso.com.",
  "Priority": 3,
  "Guid": "7a1c9f02-3b44-4e51-9d7a-2c8f6e0b14ad"
}

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

Related: GET /exchange/v1.0/labels

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

Remove the labels at /labels/{key}. Pre-checks that no label policy still references this label by its GUID (per MS Purview docs - “You can’t delete a label if it’s still in a label policy”). LabelPolicy.Labels stores GUIDs, NOT display names. Returns 409 LabelInUseByPolicy with the blocking policy names if so. Caller must then detach via PATCH /labelPolicies/{policy} with {"removeLabels":["{labelGuid}"]} first. Returns 204 on success.

State-machine guard ahead of the cmdlet: fetches the label first to resolve its internal Guid (LabelPolicy.Labels stores Guids, NOT the user-facing Name); then scans every LabelPolicy’s Labels array for a match. If any policy still publishes the label, returns 409 LabelInUseByPolicy with the blocking policy names so the caller knows what to detach first. Known residual on FFO test tenants: standalone labels (not in any policy) may still surface the opaque tenant-side “server side error” from Remove-Label even after the guard passes. This is documented in the internal notes and is not believed to occur on production tenants. IPPS-side - omitConfirm: true.

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

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

Delete a sensitivity label

Removes a MIP sensitivity label via Remove-Label. The controller pre-checks that no label policy still references the label by GUID and returns 409 LabelInUseByPolicy if so; otherwise returns 204 No Content.

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

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