Purview sensitivity labels in bulk: Excel columns and nested labels

Sensitivity labels in Microsoft Purview can be created one by one in the UI, or in bulk via Excel/CSV and Security & Compliance PowerShell (New-Label). This is not the same as retention labels / file plan — those have a different CSV. Do not mix them.

Order for nested labels

A sublabel points at its immediate parent. That parent must already exist. So create the top first (empty Parent), then the next layer, then the deepest. The last (deepest) label cannot go first: New-Label fails with parent not found.

Example: Confidential → Confidential / HR → Confidential / HR / Payroll. Row 1: Confidential (Parent empty). Row 2: HR (Parent = Confidential). Row 3: Payroll (Parent = HR). If Excel is deepest-first, sort before import.

Delete or unpublish is the reverse: deepest child first, then the parent. A parent that still has sublabels will not delete.

Excel columns

First row = headers, these names exactly. Optional cells may be empty. Name is internal and painful to rename later; DisplayName is what users see.

Sample CSV

Name,DisplayName,Tooltip,Comment,Parent,Priority,Color,HeaderEnabled,HeaderText,EncryptionEnabled
Confidential,Confidential,Company confidential,Root label,,0,#C23B22,TRUE,CONFIDENTIAL,TRUE
Confidential-HR,HR,HR only,Child of Confidential,Confidential,1,#C23B22,TRUE,HR CONFIDENTIAL,TRUE
Confidential-HR-Payroll,Payroll,Payroll only,Child of HR,Confidential-HR,2,#8B1E1E,TRUE,PAYROLL,TRUE
Internal,Internal,Internal use,Root label,,3,#2E75B6,FALSE,,FALSE

PowerShell

Compliance PowerShell, not Exchange Online. Role: Compliance Administrator or higher. App-only is possible, but the cmdlets live in the IPS session.

Connect-IPPSSession
# Security & Compliance PowerShell (not Exchange, not Graph)

$rows = Import-Csv .\labels.csv
# Parent must already exist: empty Parent first, then one level down, then the next.
$ordered = $rows | Sort-Object @{ Expression = {
    if (-not $_.Parent) { 0 } else { 1 + ($_.Parent -split '[\\/]').Count }
} }

foreach ($r in $ordered) {
    $p = @{
        Name        = $r.Name
        DisplayName = $r.DisplayName
        Tooltip     = $r.Tooltip
        Comment     = $r.Comment
    }
    if ($r.Parent) {
        $parent = Get-Label | Where-Object { $_.Name -eq $r.Parent -or $_.DisplayName -eq $r.Parent }
        if (-not $parent) { throw "Parent not found: $($r.Parent). Create the parent row first." }
        $p.ParentId = $parent.Guid
    }
    if ($r.Priority) { $p.Priority = [int]$r.Priority }
    New-Label @p
    if ($r.HeaderEnabled -eq 'TRUE') {
        Set-Label -Identity $r.Name -ApplyContentMarkingHeaderEnabled $true -ApplyContentMarkingHeaderText $r.HeaderText
    }
}

Publish

A label that is not in a label policy is invisible. Publishing the parent does not auto-publish the children — include every layer in the policy, or use separate policies per layer. Auto-labeling policies point at existing labels; those labels must already be published.

Frequent errors

Parent label not found — the parent row is not imported yet, or Parent does not match Name/DisplayName (spaces, casing). Cannot delete label that has sublabels — remove the deepest first. The term New-Label is not recognized — you are in Exchange or Graph, not in Connect-IPPSSession.