Microsoft Groups API

openapi: 3.1.0
info:
  title: Microsoft Azure Cognitive Services Accounts Groups API
  description: APIs for vision, speech, language, and decision-making AI capabilities including Computer Vision, Text Analytics, and Translator services.
  version: '3.2'
  contact:
    name: Microsoft Azure Support
    url: https://azure.microsoft.com/en-us/support/
  termsOfService: https://www.microsoft.com/en-us/legal/terms-of-use
servers:
- url: https://{region}.api.cognitive.microsoft.com
  description: Azure Cognitive Services Regional Endpoint
  variables:
    region:
      default: eastus
      description: Azure region for the Cognitive Services resource
security:
- apiKey: []
tags:
- name: Groups
  description: Manage Microsoft Entra groups including Microsoft 365 groups and security groups
paths:
  /groups:
    get:
      operationId: listGroups
      summary: Microsoft List groups
      description: List all the groups in an organization, including but not limited to Microsoft 365 groups. Returns a default set of properties for each group.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: Collection of group objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  '@odata.nextLink':
                    type: string
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createGroup
      summary: Microsoft Create group
      description: 'Create a new group as specified in the request body. You can create one of the following groups: Microsoft 365 group (unified group), security group, or mail-enabled security group.'
      tags:
      - Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreate'
      responses:
        '201':
          description: Group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /groups/{group-id}:
    get:
      operationId: getGroup
      summary: Microsoft Get group
      description: Get the properties and relationships of a group object. Returns a default set of properties unless you use $select to specify specific properties.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateGroup
      summary: Microsoft Update group
      description: Update the properties of a group object.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
      responses:
        '204':
          description: Group updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteGroup
      summary: Microsoft Delete group
      description: Delete a group. When deleted, Microsoft 365 groups are moved to a temporary container and can be restored within 30 days.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      responses:
        '204':
          description: Group deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
  /groups/{group-id}/members:
    get:
      operationId: listGroupMembers
      summary: Microsoft List group members
      description: Get a list of the group's direct members. A group can have users, organizational contacts, devices, service principals, and other groups as members.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: Collection of member directory objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/DirectoryObject'
        '404':
          $ref: '#/components/responses/NotFound'
  /groups/{group-id}/members/$ref:
    post:
      operationId: addGroupMember
      summary: Microsoft Add group member
      description: Add a member to a Microsoft 365 group or a security group through the members navigation property.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - '@odata.id'
              properties:
                '@odata.id':
                  type: string
                  description: The URL of the directory object to add as a member
                  example: https://graph.microsoft.com/v1.0/directoryObjects/{id}
      responses:
        '204':
          description: Member added successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /groups/{group-id}/owners:
    get:
      operationId: listGroupOwners
      summary: Microsoft List group owners
      description: Retrieve a list of the group's owners. The owners are a set of users or service principals who are allowed to manage the group.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/groupId'
      - $ref: '#/components/parameters/top'
      responses:
        '200':
          description: Collection of owner directory objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/DirectoryObject'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Group:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the group
          readOnly: true
        displayName:
          type: string
          description: Display name for the group
          maxLength: 256
        description:
          type: string
          description: Optional description for the group
        mail:
          type: string
          format: email
          description: SMTP address for the group
          readOnly: true
        mailEnabled:
          type: boolean
          description: Whether the group is mail-enabled
        mailNickname:
          type: string
          description: Mail alias for the group
          maxLength: 64
        securityEnabled:
          type: boolean
          description: Whether the group is a security group
        groupTypes:
          type: array
          items:
            type: string
          description: Specifies the group type. Contains 'Unified' for Microsoft 365 groups.
        visibility:
          type: string
          enum:
          - Public
          - Private
          - HiddenMembership
          description: Group visibility and join policy
        classification:
          type: string
          description: Classification for the group (low, medium, high business impact)
        createdDateTime:
          type: string
          format: date-time
          description: Timestamp of when the group was created
          readOnly: true
        renewedDateTime:
          type: string
          format: date-time
          description: Timestamp of when the group was last renewed
          readOnly: true
        expirationDateTime:
          type: string
          format: date-time
          description: Timestamp of when the group is set to expire
          readOnly: true
        isAssignableToRole:
          type: boolean
          description: Whether the group can be assigned to a Microsoft Entra role
        proxyAddresses:
          type: array
          items:
            type: string
          description: Email addresses for the group
          readOnly: true
        onPremisesSyncEnabled:
          type: boolean
          description: Whether the group is synced from on-premises AD
          readOnly: true
        membershipRule:
          type: string
          description: Rule for dynamic group membership
        membershipRuleProcessingState:
          type: string
          enum:
          - 'On'
          - Paused
          description: Whether dynamic membership processing is on or paused
        theme:
          type: string
          enum:
          - Teal
          - Purple
          - Green
          - Blue
          - Pink
          - Orange
          - Red
          description: Microsoft 365 group color theme
    ODataError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
            innerError:
              type: object
              properties:
                date:
                  type: string
                  format: date-time
                request-id:
                  type: string
                client-request-id:
                  type: string
    GroupCreate:
      type: object
      required:
      - displayName
      - mailEnabled
      - mailNickname
      - securityEnabled
      properties:
        displayName:
          type: string
          description: Display name for the group
          maxLength: 256
        description:
          type: string
          description: Optional description
        mailEnabled:
          type: boolean
          description: Whether the group is mail-enabled
        mailNickname:
          type: string
          description: Mail alias for the group
          maxLength: 64
        securityEnabled:
          type: boolean
          description: Whether the group is a security group
        groupTypes:
          type: array
          items:
            type: string
          description: Group types (include 'Unified' for Microsoft 365 group)
        visibility:
          type: string
          enum:
          - Public
          - Private
          - HiddenMembership
        members@odata.bind:
          type: array
          items:
            type: string
          description: URLs of members to add
        owners@odata.bind:
          type: array
          items:
            type: string
          description: URLs of owners to add
    DirectoryObject:
      type: object
      properties:
        '@odata.type':
          type: string
          description: OData type annotation
        id:
          type: string
          description: Unique identifier (GUID)
        deletedDateTime:
          type: string
          format: date-time
          description: Date and time when object was deleted
  parameters:
    filter:
      name: $filter
      in: query
      required: false
      description: OData filter expression
      schema:
        type: string
    groupId:
      name: group-id
      in: path
      required: true
      description: Unique identifier of the group
      schema:
        type: string
    orderby:
      name: $orderby
      in: query
      required: false
      description: OData order by expression
      schema:
        type: string
    count:
      name: $count
      in: query
      required: false
      description: Include count of items in the response
      schema:
        type: boolean
    skip:
      name: $skip
      in: query
      required: false
      description: Number of items to skip for pagination
      schema:
        type: integer
        minimum: 0
    select:
      name: $select
      in: query
      required: false
      description: Comma-separated list of properties to include in the response
      schema:
        type: string
    top:
      name: $top
      in: query
      required: false
      description: Number of items to return (page size)
      schema:
        type: integer
        minimum: 1
    search:
      name: $search
      in: query
      required: false
      description: Search expression to filter results
      schema:
        type: string
  responses:
    Unauthorized:
      description: Unauthorized - authentication required or token expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    BadRequest:
      description: Bad request - invalid input or malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  securitySchemes:
    apiKey:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
      description: Azure Cognitive Services subscription key
externalDocs:
  description: Azure AI Services Documentation
  url: https://learn.microsoft.com/en-us/azure/ai-services/