Microsoft Graph Group Lifecycle Policies let administrators govern the lifespan of Microsoft 365 groups by setting an expiration period, scoping the policy to all or selected groups, and automating renewal and cleanup. When a group nears expiration, owners (and optional alternate email recipients) receive reminder emails; if not renewed, the group is soft‑deleted and can be restored within a grace period.
openapi: 3.1.0
info:
title: Microsoft Graph Grouplifecyclepolicies
description: Needs a description.
paths:
/groupLifecyclePolicies:
description: >-
Provides operations to manage the collection of groupLifecyclePolicy
entities.
get:
tags:
- groupLifecyclePolicies.groupLifecyclePolicy
summary: Microsoft Graph List groupLifecyclePolicies
description: List all the groupLifecyclePolicies.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/grouplifecyclepolicy-list?view=graph-rest-1.0
operationId: groupLifecyclePolicies.groupLifecyclePolicy.ListGroupLifecyclePolicy
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.groupLifecyclePolicyCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- groupLifecyclePolicies.groupLifecyclePolicy
summary: Microsoft Graph Create groupLifecyclePolicy
description: >-
Creates a new groupLifecyclePolicy. Only one policy exists in the
tenant.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/grouplifecyclepolicy-post-grouplifecyclepolicies?view=graph-rest-1.0
operationId: groupLifecyclePolicies.groupLifecyclePolicy.CreateGroupLifecyclePolicy
requestBody:
description: New entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.groupLifecyclePolicy'
required: true
responses:
2XX:
description: Created entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.groupLifecyclePolicy'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/groupLifecyclePolicies/{groupLifecyclePolicy-id}:
description: >-
Provides operations to manage the collection of groupLifecyclePolicy
entities.
get:
tags:
- groupLifecyclePolicies.groupLifecyclePolicy
summary: Microsoft Graph Get groupLifecyclePolicy
description: >-
Retrieve the properties and relationships of a groupLifecyclePolicies
object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/grouplifecyclepolicy-get?view=graph-rest-1.0
operationId: groupLifecyclePolicies.groupLifecyclePolicy.GetGroupLifecyclePolicy
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.groupLifecyclePolicy'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- groupLifecyclePolicies.groupLifecyclePolicy
summary: Microsoft Graph Update groupLifecyclePolicy
description: >-
Update the properties of a groupLifecyclePolicygroupLifecyclePolicy
resource type object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/grouplifecyclepolicy-update?view=graph-rest-1.0
operationId: groupLifecyclePolicies.groupLifecyclePolicy.UpdateGroupLifecyclePolicy
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.groupLifecyclePolicy'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.groupLifecyclePolicy'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- groupLifecyclePolicies.groupLifecyclePolicy
summary: Microsoft Graph Delete groupLifecyclePolicy
description: Delete a groupLifecyclePolicy.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/grouplifecyclepolicy-delete?view=graph-rest-1.0
operationId: groupLifecyclePolicies.groupLifecyclePolicy.DeleteGroupLifecyclePolicy
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: groupLifecyclePolicy-id
in: path
description: The unique identifier of groupLifecyclePolicy
required: true
schema:
type: string
x-ms-docs-key-type: groupLifecyclePolicy
/groupLifecyclePolicies/{groupLifecyclePolicy-id}/addGroup:
description: Provides operations to call the addGroup method.
post:
tags:
- groupLifecyclePolicies.groupLifecyclePolicy.Actions
summary: Microsoft Graph Invoke action addGroup
description: >-
Add a group to a groupLifecyclePolicy. This action is supported only if
the managedGroupTypes property of the policy is set to Selected.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/grouplifecyclepolicy-addgroup?view=graph-rest-1.0
operationId: groupLifecyclePolicies.groupLifecyclePolicy.addGroup
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
groupId:
type: string
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
properties:
value:
type: boolean
default: false
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
parameters:
- name: groupLifecyclePolicy-id
in: path
description: The unique identifier of groupLifecyclePolicy
required: true
schema:
type: string
x-ms-docs-key-type: groupLifecyclePolicy
/groupLifecyclePolicies/{groupLifecyclePolicy-id}/removeGroup:
description: Provides operations to call the removeGroup method.
post:
tags:
- groupLifecyclePolicies.groupLifecyclePolicy.Actions
summary: Microsoft Graph Invoke action removeGroup
description: Removes a group from a lifecycle policy.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/grouplifecyclepolicy-removegroup?view=graph-rest-1.0
operationId: groupLifecyclePolicies.groupLifecyclePolicy.removeGroup
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
groupId:
type: string
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
properties:
value:
type: boolean
default: false
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
parameters:
- name: groupLifecyclePolicy-id
in: path
description: The unique identifier of groupLifecyclePolicy
required: true
schema:
type: string
x-ms-docs-key-type: groupLifecyclePolicy
/groupLifecyclePolicies/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- groupLifecyclePolicies.groupLifecyclePolicy
summary: Microsoft Graph Get the number of the resource
operationId: groupLifecyclePolicies.GetCount-ca62
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
/groups/{group-id}/groupLifecyclePolicies:
description: >-
Provides operations to manage the groupLifecyclePolicies property of the
microsoft.graph.group entity.
get:
tags:
- groups.groupLifecyclePolicy
summary: Microsoft Graph List groupLifecyclePolicies
description: >-
Retrieves a list of groupLifecyclePolicy objects to which a group
belongs.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/group-list-grouplifecyclepolicies?view=graph-rest-1.0
operationId: groups.ListGroupLifecyclePolicies
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.groupLifecyclePolicyCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- groups.groupLifecyclePolicy
summary: Microsoft Graph Create new navigation property to groupLifecyclePolicies for groups
operationId: groups.CreateGroupLifecyclePolicies
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.groupLifecyclePolicy'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.groupLifecyclePolicy'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: group-id
in: path
description: The unique identifier of group
required: true
schema:
type: string
x-ms-docs-key-type: group
/groups/{group-id}/groupLifecyclePolicies/{groupLifecyclePolicy-id}:
description: >-
Provides operations to manage the groupLifecyclePolicies property of the
microsoft.graph.group entity.
get:
tags:
- groups.groupLifecyclePolicy
summary: Microsoft Graph Get groupLifecyclePolicies from groups
description: >-
The collection of lifecycle policies for this group. Read-only.
Nullable.
operationId: groups.GetGroupLifecyclePolicies
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.groupLifecyclePolicy'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- groups.groupLifecyclePolicy
summary: Microsoft Graph Update the navigation property groupLifecyclePolicies in groups
operationId: groups.UpdateGroupLifecyclePolicies
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.groupLifecyclePolicy'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.groupLifecyclePolicy'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- groups.groupLifecyclePolicy
summary: Microsoft Graph Delete navigation property groupLifecyclePolicies for groups
operationId: groups.DeleteGroupLifecyclePolicies
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: group-id
in: path
description: The unique identifier of group
required: true
schema:
type: string
x-ms-docs-key-type: group
- name: groupLifecyclePolicy-id
in: path
description: The unique identifier of groupLifecyclePolicy
required: true
schema:
type: string
x-ms-docs-key-type: groupLifecyclePolicy
/groups/{group-id}/groupLifecyclePolicies/{groupLifecyclePolicy-id}/addGroup:
description: Provides operations to call the addGroup method.
post:
tags:
- groups.groupLifecyclePolicy
summary: Microsoft Graph Invoke action addGroup
description: >-
Add a group to a groupLifecyclePolicy. This action is supported only if
the managedGroupTypes property of the policy is set to Selected.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/grouplifecyclepolicy-addgroup?view=graph-rest-1.0
operationId: groups.group.groupLifecyclePolicies.groupLifecyclePolicy.addGroup
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
groupId:
type: string
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
properties:
value:
type: boolean
default: false
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
parameters:
- name: group-id
in: path
description: The unique identifier of group
required: true
schema:
type: string
x-ms-docs-key-type: group
- name: groupLifecyclePolicy-id
in: path
description: The unique identifier of groupLifecyclePolicy
required: true
schema:
type: string
x-ms-docs-key-type: groupLifecyclePolicy
/groups/{group-id}/groupLifecyclePolicies/{groupLifecyclePolicy-id}/removeGroup:
description: Provides operations to call the removeGroup method.
post:
tags:
- groups.groupLifecyclePolicy
summary: Microsoft Graph Invoke action removeGroup
description: Removes a group from a lifecycle policy.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/grouplifecyclepolicy-removegroup?view=graph-rest-1.0
operationId: groups.group.groupLifecyclePolicies.groupLifecyclePolicy.removeGroup
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
groupId:
type: string
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
properties:
value:
type: boolean
default: false
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
parameters:
- name: group-id
in: path
description: The unique identifier of group
required: true
schema:
type: string
x-ms-docs-key-type: group
- name: groupLifecyclePolicy-id
in: path
description: The unique identifier of groupLifecyclePolicy
required: true
schema:
type: string
x-ms-docs-key-type: groupLifecyclePolicy
/groups/{group-id}/groupLifecyclePolicies/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- groups.groupLifecyclePolicy
summary: Microsoft Graph Get the number of the resource
operationId: groups.groupLifecyclePolicies.GetCount-ba70
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: group-id
in: path
description: The unique identifier of group
required: true
schema:
type: string
x-ms-docs-key-type: group
components:
schemas:
microsoft.graph.groupLifecyclePolicy:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: groupLifecyclePolicy
required:
- '@odata.type'
type: object
properties:
alternateNotificationEmails:
type: string
description: >-
List of email address to send notifications for groups without
owners. Multiple email address can be defined by separating
email address with a semicolon.
nullable: true
groupLifetimeInDays:
maximum: 2147483647
minimum: -2147483648
type: number
description: >-
Number of days before a group expires and needs to be renewed.
Once renewed, the group expiration is extended by the number of
days defined.
format: int32
nullable: true
managedGroupTypes:
type: string
description: >-
The group type for which the expiration policy applies. Possible
values are All, Selected or None.
nullable: true
'@odata.type':
type: string
x-ms-discriminator-value: '#microsoft.graph.groupLifecyclePolicy'
parameters:
top:
name: $top
in: query
description: Show only the first n items
style: form
explode: false
schema:
minimum: 0
type: integer
example: 50
skip:
name: $skip
in: query
description: Skip the first n items
style: form
explode: false
schema:
minimum: 0
type: integer
search:
name: $search
in: query
description: Search items by search phrases
style: form
explode: false
schema:
type: string
filter:
name: $filter
in: query
description: Filter items by property values
style: form
explode: false
schema:
type: string
count:
name: $count
in: query
description: Include count of items
style: form
explode: false
schema:
type: boolean
examples: {}
responses:
error:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.ODataErrors.ODataError'
ODataCountResponse:
description: The count of the resource
content:
text/plain:
schema:
$ref: '#/components/schemas/ODataCountResponse'
tags:
- name: groupLifecyclePolicies.groupLifecyclePolicy
- name: groupLifecyclePolicies.groupLifecyclePolicy.Actions
- name: groups.groupLifecyclePolicy