Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Microsoft Graph Admin Admin.admin Groups.group API
description: 'Microsoft Graph API for managing administrative resources in Microsoft Entra ID.
This API enables administrators to manage Microsoft Edge browser settings, Internet Explorer mode configurations,
site lists, shared browser sites, Microsoft 365 Apps installation options, people insights, service announcements,
SharePoint settings, Copilot administration, directory administrative units, and admin consent policies.'
version: 1.0.0
contact:
name: Microsoft Graph API Support
url: https://developer.microsoft.com/graph
servers:
- url: https://graph.microsoft.com/v1.0
description: Microsoft Graph API v1.0 endpoint
tags:
- name: Groups.group
paths:
/groups:
description: Provides operations to manage the collection of group entities.
get:
tags:
- Groups.group
summary: Microsoft Graph List groups
description: List all the groups available in an organization, excluding dynamic distribution groups. To retrieve dynamic distribution groups, use the Exchange admin center. This operation returns by default only a subset of the properties for each group. These default properties are noted in the Properties section. To get properties that are not returned by default, do a GET operation for the group and specify the properties in a $select OData query option. The hasMembersWithLicenseErrors and isArchived properties are an exception and are not returned in the $select query.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/group-list?view=graph-rest-1.0
operationId: groups.group.ListGroup
parameters:
- name: ConsistencyLevel
in: header
description: 'Indicates the requested consistency level. Documentation URL: https://docs.microsoft.com/graph/aad-advanced-queries'
schema:
type: string
examples:
example-1:
description: $search and $count queries require the client to set the ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $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.groupCollectionResponse'
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.group
summary: Microsoft Graph Create group
description: 'Create a new group as specified in the request body. You can create the following types of groups: This operation returns by default only a subset of the properties for each group. These default properties are noted in the Properties section. To get properties that are not returned by default, do a GET operation and specify the properties in a $select OData query option.'
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/group-post-groups?view=graph-rest-1.0
operationId: groups.group.CreateGroup
requestBody:
description: New entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.group'
required: true
responses:
2XX:
description: Created entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.group'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/groups/{group-id}:
description: Provides operations to manage the collection of group entities.
parameters:
- name: group-id
in: path
description: The unique identifier of group
required: true
schema:
type: string
x-ms-docs-key-type: group
get:
tags:
- Groups.group
summary: Microsoft Graph Get group
description: Get the properties and relationships of a group object. This operation returns by default only a subset of all the available properties, as noted in the Properties section. To get properties that aren't_ returned by default, specify them in a $select OData query option. The hasMembersWithLicenseErrors and isArchived properties are an exception and aren't returned in the $select query.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/group-get?view=graph-rest-1.0
operationId: groups.group.GetGroup
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.group'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- Groups.group
summary: Microsoft Graph Upsert group
description: 'Create a new group object if it doesn''t exist, or update the properties of an existing group object.
You can create or update the following types of group: By default, this operation returns only a subset of the properties for each group. For a list of properties that are returned by default, see the Properties section of the group resource. To get properties that are not returned by default, do a GET operation and specify the properties in a $select OData query option.'
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/group-upsert?view=graph-rest-1.0
operationId: groups.group.UpdateGroup
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.group'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.group'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- Groups.group
summary: Microsoft Graph Delete group
description: Delete a group. When deleted, both Microsoft 365 and security groups are moved to a temporary container and can be restored within 30 days. After that time, they're permanently deleted. This doesn't apply to Distribution groups which are permanently deleted immediately. To learn more, see deletedItems.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/group-delete?view=graph-rest-1.0
operationId: groups.group.DeleteGroup
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
/groups(uniqueName='{uniqueName}'):
description: Provides operations to manage the collection of group entities.
parameters:
- name: uniqueName
in: path
description: Alternate key of group
required: true
schema:
type: string
nullable: true
get:
tags:
- Groups.group
summary: Microsoft Graph Get group
description: Get the properties and relationships of a group object. This operation returns by default only a subset of all the available properties, as noted in the Properties section. To get properties that aren't_ returned by default, specify them in a $select OData query option. The hasMembersWithLicenseErrors and isArchived properties are an exception and aren't returned in the $select query.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/group-get?view=graph-rest-1.0
operationId: groups.group.GetGroupByUniqueName
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.group'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- Groups.group
summary: Microsoft Graph Upsert group
description: 'Create a new group object if it doesn''t exist, or update the properties of an existing group object.
You can create or update the following types of group: By default, this operation returns only a subset of the properties for each group. For a list of properties that are returned by default, see the Properties section of the group resource. To get properties that are not returned by default, do a GET operation and specify the properties in a $select OData query option.'
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/group-upsert?view=graph-rest-1.0
operationId: groups.group.UpdateGroupByUniqueName
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.group'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.group'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- Groups.group
summary: Microsoft Graph Delete group
description: Delete a group. When deleted, both Microsoft 365 and security groups are moved to a temporary container and can be restored within 30 days. After that time, they're permanently deleted. This doesn't apply to Distribution groups which are permanently deleted immediately. To learn more, see deletedItems.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/group-delete?view=graph-rest-1.0
operationId: groups.group.DeleteGroupByUniqueName
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
/groups/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- Groups.group
summary: Microsoft Graph Get the number of the resource
operationId: groups.GetCount-044a
parameters:
- name: ConsistencyLevel
in: header
description: 'Indicates the requested consistency level. Documentation URL: https://docs.microsoft.com/graph/aad-advanced-queries'
schema:
type: string
examples:
example-1:
description: $search and $count queries require the client to set the ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
components:
schemas:
microsoft.graph.listInfo:
title: listInfo
required:
- '@odata.type'
type: object
properties:
contentTypesEnabled:
type: boolean
description: If true, indicates that content types are enabled for this list.
nullable: true
hidden:
type: boolean
description: If true, indicates that the list isn't normally visible in the SharePoint user experience.
nullable: true
template:
type: string
description: An enumerated value that represents the base list template used in creating the list. Possible values include documentLibrary, genericList, task, survey, announcements, contacts, and more.
nullable: true
'@odata.type':
type: string
microsoft.graph.sizeRange:
title: sizeRange
required:
- '@odata.type'
type: object
properties:
maximumSize:
maximum: 2147483647
minimum: -2147483648
type: number
description: The maximum size (in kilobytes) that an incoming message must have in order for a condition or exception to apply.
format: int32
nullable: true
minimumSize:
maximum: 2147483647
minimum: -2147483648
type: number
description: The minimum size (in kilobytes) that an incoming message must have in order for a condition or exception to apply.
format: int32
nullable: true
'@odata.type':
type: string
microsoft.graph.virtualEventExternalRegistrationInformation:
title: virtualEventExternalRegistrationInformation
required:
- '@odata.type'
type: object
properties:
referrer:
type: string
description: A URL or string that represents the location from which the registrant registered. Optional.
nullable: true
registrationId:
type: string
description: The identifier for a virtualEventExternalRegistrationInformation object. Optional. If set, the maximum supported length is 256 characters.
nullable: true
'@odata.type':
type: string
microsoft.graph.windowsDeviceHealthState:
title: windowsDeviceHealthState
enum:
- clean
- fullScanPending
- rebootPending
- manualStepsPending
- offlineScanPending
- critical
type: string
description: Computer endpoint protection state
x-ms-enum-flags:
isFlags: true
x-ms-enum:
name: windowsDeviceHealthState
modelAsString: false
values:
- value: clean
description: Computer is clean and no action is required
name: clean
- value: fullScanPending
description: Computer is in pending full scan state
name: fullScanPending
- value: rebootPending
description: Computer is in pending reboot state
name: rebootPending
- value: manualStepsPending
description: Computer is in pending manual steps state
name: manualStepsPending
- value: offlineScanPending
description: Computer is in pending offline scan state
name: offlineScanPending
- value: critical
description: Computer is in critical failure state
name: critical
microsoft.graph.identity:
title: identity
required:
- '@odata.type'
type: object
properties:
displayName:
type: string
description: The display name of the identity.For drive items, the display name might not always be available or up to date. For example, if a user changes their display name the API might show the new value in a future response, but the items associated with the user don't show up as changed when using delta.
nullable: true
id:
type: string
description: Unique identifier for the identity or actor. For example, in the access reviews decisions API, this property might record the id of the principal, that is, the group, user, or application that's subject to review.
nullable: true
'@odata.type':
type: string
discriminator:
propertyName: '@odata.type'
mapping:
'#microsoft.graph.azureCommunicationServicesUserIdentity': '#/components/schemas/microsoft.graph.azureCommunicationServicesUserIdentity'
'#microsoft.graph.communicationsApplicationIdentity': '#/components/schemas/microsoft.graph.communicationsApplicationIdentity'
'#microsoft.graph.communicationsApplicationInstanceIdentity': '#/components/schemas/microsoft.graph.communicationsApplicationInstanceIdentity'
'#microsoft.graph.communicationsEncryptedIdentity': '#/components/schemas/microsoft.graph.communicationsEncryptedIdentity'
'#microsoft.graph.communicationsGuestIdentity': '#/components/schemas/microsoft.graph.communicationsGuestIdentity'
'#microsoft.graph.communicationsPhoneIdentity': '#/components/schemas/microsoft.graph.communicationsPhoneIdentity'
'#microsoft.graph.communicationsUserIdentity': '#/components/schemas/microsoft.graph.communicationsUserIdentity'
'#microsoft.graph.emailIdentity': '#/components/schemas/microsoft.graph.emailIdentity'
'#microsoft.graph.initiator': '#/components/schemas/microsoft.graph.initiator'
'#microsoft.graph.provisionedIdentity': '#/components/schemas/microsoft.graph.provisionedIdentity'
'#microsoft.graph.provisioningServicePrincipal': '#/components/schemas/microsoft.graph.provisioningServicePrincipal'
'#microsoft.graph.provisioningSystem': '#/components/schemas/microsoft.graph.provisioningSystem'
'#microsoft.graph.servicePrincipalIdentity': '#/components/schemas/microsoft.graph.servicePrincipalIdentity'
'#microsoft.graph.sharePointIdentity': '#/components/schemas/microsoft.graph.sharePointIdentity'
'#microsoft.graph.teamworkApplicationIdentity': '#/components/schemas/microsoft.graph.teamworkApplicationIdentity'
'#microsoft.graph.teamworkConversationIdentity': '#/components/schemas/microsoft.graph.teamworkConversationIdentity'
'#microsoft.graph.teamworkTagIdentity': '#/components/schemas/microsoft.graph.teamworkTagIdentity'
'#microsoft.graph.teamworkUserIdentity': '#/components/schemas/microsoft.graph.teamworkUserIdentity'
'#microsoft.graph.userIdentity': '#/components/schemas/microsoft.graph.userIdentity'
'#microsoft.graph.callRecords.userIdentity': '#/components/schemas/microsoft.graph.callRecords.userIdentity'
microsoft.graph.appLogUploadState:
title: appLogUploadState
enum:
- pending
- completed
- failed
- unknownFutureValue
type: string
description: AppLogUploadStatus
x-ms-enum:
name: appLogUploadState
modelAsString: false
values:
- value: pending
description: Default. Indicates that request is waiting to be processed or under processing.
name: pending
- value: completed
description: Indicates that request is completed with file uploaded to Azure blob for download.
name: completed
- value: failed
description: Indicates that request is completed with file uploaded to Azure blob for download.
name: failed
- value: unknownFutureValue
description: Evolvable enumeration sentinel value. Do not use.
name: unknownFutureValue
microsoft.graph.workbookIcon:
title: workbookIcon
required:
- '@odata.type'
type: object
properties:
index:
maximum: 2147483647
minimum: -2147483648
type: number
description: The index of the icon in the given set.
format: int32
set:
type: string
description: 'The set that the icon is part of. The possible values are: Invalid, ThreeArrows, ThreeArrowsGray, ThreeFlags, ThreeTrafficLights1, ThreeTrafficLights2, ThreeSigns, ThreeSymbols, ThreeSymbols2, FourArrows, FourArrowsGray, FourRedToBlack, FourRating, FourTrafficLights, FiveArrows, FiveArrowsGray, FiveRating, FiveQuarters, ThreeStars, ThreeTriangles, FiveBoxes.'
'@odata.type':
type: string
microsoft.graph.specialFolder:
title: specialFolder
required:
- '@odata.type'
type: object
properties:
name:
type: string
description: The unique identifier for this item in the /drive/special collection
nullable: true
'@odata.type':
type: string
microsoft.graph.operationStatus:
title: operationStatus
enum:
- NotStarted
- Running
- Completed
- Failed
type: string
microsoft.graph.scopedRoleMembership:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: scopedRoleMembership
required:
- '@odata.type'
type: object
properties:
administrativeUnitId:
type: string
description: Unique identifier for the administrative unit that the directory role is scoped to
roleId:
type: string
description: Unique identifier for the directory role that the member is in.
roleMemberInfo:
$ref: '#/components/schemas/microsoft.graph.identity'
'@odata.type':
type: string
x-ms-discriminator-value: '#microsoft.graph.scopedRoleMembership'
microsoft.graph.sensitivityLabel:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: sensitivityLabel
required:
- '@odata.type'
type: object
properties:
actionSource:
anyOf:
- $ref: '#/components/schemas/microsoft.graph.labelActionSource'
- type: object
nullable: true
autoTooltip:
type: string
nullable: true
description:
type: string
nullable: true
displayName:
type: string
nullable: true
isDefault:
type: boolean
nullable: true
isEndpointProtectionEnabled:
type: boolean
nullable: true
isScopedToUser:
type: boolean
nullable: true
locale:
type: string
nullable: true
name:
type: string
nullable: true
priority:
maximum: 2147483647
minimum: -2147483648
type: number
format: int32
nullable: true
toolTip:
type: string
nullable: true
rights:
anyOf:
- $ref: '#/components/schemas/microsoft.graph.usageRightsIncluded'
- type: object
nullable: true
x-ms-navigationProperty: true
sublabels:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.sensitivityLabel'
x-ms-navigationProperty: true
'@odata.type':
type: string
x-ms-discriminator-value: '#microsoft.graph.sensitivityLabel'
microsoft.graph.calendarRoleType:
title: calendarRoleType
enum:
- none
- freeBusyRead
- limitedRead
- read
- write
- delegateWithoutPrivateEventAccess
- delegateWithPrivateEventAccess
- custom
type: string
microsoft.graph.workbookOperation:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: workbookOperation
required:
- '@odata.type'
type: object
properties:
error:
anyOf:
- $ref: '#/components/schemas/microsoft.graph.workbookOperationError'
- type: object
nullable: true
description: The error returned by the operation.
resourceLocation:
type: string
description: The resource URI for the result.
nullable: true
status:
$ref: '#/components/schemas/microsoft.graph.workbookOperationStatus'
'@odata.type':
type: string
x-ms-discriminator-value: '#microsoft.graph.workbookOperation'
microsoft.graph.chatType:
title: chatType
enum:
- oneOnOne
- group
- meeting
- unknownFutureValue
type: string
microsoft.graph.workbookTableSort:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: workbookTableSort
required:
- '@odata.type'
type: object
properties:
fields:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.workbookSortField'
description: The list of the current conditions last used to sort the table. Read-only.
matchCase:
type: boolean
description: Indicates whether the casing impacted the last sort of the table. Read-only.
method:
type: string
description: 'The Chinese character ordering method last used to sort the table. The possible values are: PinYin, StrokeCount. Read-only.'
'@odata.type':
type: string
x-ms-discriminator-value: '#microsoft.graph.workbookTableSort'
microsoft.graph.teamVisibilityType:
title: teamVisibilityType
enum:
- private
- public
- hiddenMembership
- unknownFutureValue
type: string
microsoft.graph.oAuth2PermissionGrant:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: oAuth2PermissionGrant
required:
- '@odata.type'
type: object
properties:
clientId:
type: string
description: The object id (not appId) of the client service principal for the application that's authorized to act on behalf of a signed-in user when accessing an API. Required. Supports $filter (eq only).
consentType:
type: string
description: Indicates if authorization is granted for the client application to impersonate all users or only a specific user. AllPrincipals indicates authorization to impersonate all users. Principal indicates authorization to impersonate a specific user. Consent on behalf of all users can be granted by an administrator. Nonadmin users might be authorized to consent on behalf of themselves in some cases, for some delegated permissions. Required. Supports $filter (eq only).
nullable: true
principalId:
type: string
description: The id of the user on behalf of whom the client is authorized to access the resource, when consentType is Principal. If consentType is AllPrincipals this value is null. Required when consentType is Principal. Supports $filter (eq only).
nullable: true
resourceId:
type: string
description: The id of the resource service principal to which access is authorized. This identifies the API that the client is authorized to attempt to call on behalf of a signed-in user. Supports $filter (eq only).
scope:
type: string
description: A space-separated list of the claim values for delegated permissions that should be included in access tokens for the resource application (the API). For example, openid User.Read GroupMember.Read.All. Each claim value should match the value field of one of the delegated permissions defined by the API, listed in the oauth2PermissionScopes property of the resource service principal. Must not exceed 3,850 characters in length.
nullable: true
'@odata.type':
type: string
x-ms-discriminator-value: '#microsoft.graph.oAuth2PermissionGrant'
microsoft.graph.shiftItem:
allOf:
- $ref: '#/components/schemas/microsoft.graph.scheduleEntity'
- title: shiftItem
required:
- '@odata.type'
type: object
properties:
activities:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.shiftActivity'
description: An incremental part of a shift which can cover details of when and where an employee is during their shift. For example, an assignment or a scheduled break or lunch. Required.
displayName:
type: string
description: The shift label of the shiftItem.
nullable: true
notes:
type: string
description: The shift notes for the shiftItem.
nullable: true
'@odata.type':
type: string
discriminator:
propertyName: '@odata.type'
mapping:
'#microsoft.graph.openShiftItem': '#/components/schemas/microsoft.graph.openShiftItem'
microsoft.graph.plannerContainerType:
title: plannerContainerType
enum:
- group
- unknownFutureValue
- roster
type: string
microsoft.graph.conversation:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: conversation
required:
- '@odata.type'
type: object
properties:
hasAttachments:
type: boolean
description: Indicates whether any of the posts within this Conversation has at least one attachment. Supports $filter (eq, ne) and $search.
lastDeliveredDateTime:
pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
type: string
description: The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z
format: date-time
preview:
type: string
description: A short summary from the body of the latest post in this conversation. Supports $filter (eq, ne, le, ge).
topic:
type: string
description: The topic of the conversation. This property can be set when the conversation is created, but it cannot be updated.
uniqueSenders:
type: array
items:
type: string
description: All the users that sent
# --- truncated at 32 KB (1006 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-graph/refs/heads/main/openapi/microsoft-graph-groups-group-api-openapi.yml