adaptiveScopes

Adaptive Scopes. Dynamic query-based scopes targeting users, groups, or sites. The adaptiveScopes entity set lives under /exchange/v1.0/adaptiveScopes in the Governance & protection category.

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

Routes

Method	Path	Synopsis	Role	Plan
GET	/exchange/v1.0/adaptiveScopes	List adaptiveScopes entries.	Compliance.IPPS.Read	Community
POST	/exchange/v1.0/adaptiveScopes	Create a new adaptiveScopes entry. Body keys map 1:1 to New-AdaptiveScope parameter names (camelCased). Required: name + locationType. Provide either filterConditions (PswsHashtable / dictionary) OR rawQuery (KQL string) - parameter-set discriminator. Returns 201 + Location + the freshly-fetched scope.	Compliance.IPPS.ReadWrite	Enterprise
GET	/exchange/v1.0/adaptiveScopes/{key}	Get a single adaptiveScopes entry by Identity.	Compliance.IPPS.Read	Community
PATCH	/exchange/v1.0/adaptiveScopes/{key}	Partial update of the adaptiveScopes at /adaptiveScopes/{key}. Body keys map 1:1 to Set-AdaptiveScope parameters. Returns 200 + the post-Set scope.	Compliance.IPPS.ReadWrite	Enterprise
DELETE	/exchange/v1.0/adaptiveScopes/{key}	Remove the adaptiveScopes at /adaptiveScopes/{key}. Returns 204 with no body.	Compliance.IPPS.ReadWrite	Enterprise

GET /exchange/v1.0/adaptiveScopes

List adaptiveScopes entries.

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

Parameter	In	Type	Required	Description
locationTypes	query	string		Filter by LocationTypes (User, Group, SharePoint, …).
administrativeUnits	query	string		Scope results to one or more administrative units (Wiki -AdministrativeUnits). Useful in delegated-admin tenants.

List Purview adaptive policy scopes

Lists adaptive policy scopes via Get-AdaptiveScope (IPPS pool). Each scope is a dynamic recipient/site/group population resolved by attribute filters; used by retention, DLP, and label policies as their target audience. Optional ?locationTypes filters by workload (User, Group, SharePoint, …).

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

HTTP/1.1 200 OK

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#adaptiveScopes",
  "value": [
    {
      "Id": "scope-engineering-emea-guid",
      "Name": "Engineering EMEA",
      "Identity": "scope-engineering-emea-guid",
      "LocationType": "User",
      "Comment": "Adaptive scope for retention on Engineering team in EMEA."
    }
  ]
}

Related: GET /exchange/v1.0/adaptiveScopes/{key}, GET /exchange/v1.0/adaptiveScopeMembers?scope={scope}

POST /exchange/v1.0/adaptiveScopes

Create a new adaptiveScopes entry. Body keys map 1:1 to New-AdaptiveScope parameter names (camelCased). Required: name + locationType. Provide either filterConditions (PswsHashtable / dictionary) OR rawQuery (KQL string) - parameter-set discriminator. Returns 201 + Location + the freshly-fetched scope.

Creates a dynamic, filter-based recipient/site/group population used by retention / DLP / label policies. locationType selects User / Group / SharePoint and gates which filter properties are valid. Choose ONE filter mode: filterConditions (a PswsHashtable / dictionary tree, e.g. { “Conditions”: […] }) OR rawQuery (a KQL string). Passing both is rejected by the cmdlet’s parameter-set discriminator. IPPS-side - controller passes omitConfirm: true. Newly created scopes are immediately usable as policy targets - there’s no distribution-pending state for adaptive scopes themselves.

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

Parameter	In	Type	Required	Description
locationType	body		yes
name	body		yes
administrativeUnit	body
comment	body
filterConditions	body
rawQuery	body
dryRun	query	bool (switch)

Create an adaptive policy scope

Create a Purview adaptive scope via New-AdaptiveScope on the IPPS pool. Required: name + locationType (User | Group | Site). Provide EITHER filterConditions (a PswsHashtable tree of attribute filters) OR rawQuery (an OPATH/Entra filter string) - the cmdlet’s parameter-set discriminator picks the right code path. Tier 5 IPPS - backed by Compliance.IPPS.ReadWrite.All.

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

{
  "name": "finance-team-emea",
  "locationType": "User",
  "rawQuery": "Department -eq 'Finance' -and Country -eq 'FR'",
  "comment": "Adaptive scope for retention on Finance team in EMEA."
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/adaptiveScopes/finance-team-emea

{
  "@odata.context": "https://api.contoso.com/exchange/v1.0/$metadata#adaptiveScopes/$entity",
  "Id": "scope-finance-team-emea-guid",
  "Name": "finance-team-emea",
  "Identity": "scope-finance-team-emea-guid",
  "LocationType": "User",
  "Comment": "Adaptive scope for retention on Finance team in EMEA.",
  "AdministrativeUnits": []
}

Related: GET /exchange/v1.0/adaptiveScopes/{key}, PATCH /exchange/v1.0/adaptiveScopes/{key}, DELETE /exchange/v1.0/adaptiveScopes/{key}, GET /exchange/v1.0/adaptiveScopeMembers?scope={scopeId}

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

Get a single adaptiveScopes entry by Identity.

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

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

Partial update of the adaptiveScopes at /adaptiveScopes/{key}. Body keys map 1:1 to Set-AdaptiveScope parameters. Returns 200 + the post-Set scope.

Use this endpoint to swap a scope’s filter (e.g. flip filterConditions → rawQuery, or change the KQL/predicate tree). The cmdlet permits either filter mode on update but rejects passing both simultaneously. The scope’s locationType is immutable after creation - to change User → Group (or similar), DELETE + re-POST.IPPS-side - controller passes omitConfirm: true. Membership refresh against the new filter is asynchronous; GET /adaptiveScopeMembers?scope={key} may lag briefly behind the Set call.

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

Parameter	In	Type	Required	Description
administrativeUnit	body
comment	body
filterConditions	body
rawQuery	body
dryRun	query	bool (switch)

Update an adaptive scope’s filter or comment

Partial update of the adaptive scope at /adaptiveScopes/{key}. Backed by the Set-AdaptiveScope cmdlet; body keys map 1:1 to its parameters (camelCased). The locationType is immutable after creation.

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

{
  "rawQuery": "Department -eq 'Sales' -and CountryOrRegion -eq 'US'",
  "comment": "exonaut-sample-adaptiveScopes updated to US Sales population"
}

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

{
  "Id": "exonaut-sample-adaptiveScopes",
  "Identity": "exonaut-sample-adaptiveScopes",
  "Name": "exonaut-sample-adaptiveScopes",
  "LocationType": "User",
  "RawQuery": "Department -eq 'Sales' -and CountryOrRegion -eq 'US'",
  "Comment": "exonaut-sample-adaptiveScopes updated to US Sales population"
}

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

Related: GET /exchange/v1.0/adaptiveScopes

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

Remove the adaptiveScopes at /adaptiveScopes/{key}. Returns 204 with no body.

Adaptive scopes have no distribution-pending state, so no pre-DELETE guard is needed here. However, a scope referenced by an active retention / DLP / label policy will be rejected by the cmdlet with a tenant-side error - detach the scope from referencing policies first (PATCH the policy with the appropriate remove*Location param). IPPS-side - omitConfirm: true. Pass ?dryRun=true to map to -WhatIf.

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

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Delete an adaptive scope

Removes the adaptive scope at /adaptiveScopes/{key}. Backed by the Remove-AdaptiveScope cmdlet. A scope referenced by an active retention, DLP, or label policy is rejected by the cmdlet until detached. Returns 204 with no body.

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

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