Microsoft Entra ID (formerly Azure AD) Subscriptions.subscription API

openapi: 3.2.0
info:
  title: ChangeNotifications Subscriptions.subscription API
  version: v1.0
servers:
- url: https://graph.microsoft.com/v1.0/
  description: Core
security:
- azureaadv2: []
tags:
- name: Subscriptions subscription
paths:
  /subscriptions:
    get:
      tags:
      - Subscriptions subscription
      summary: List subscriptions
      description: Retrieve the properties and relationships of webhook subscriptions, based on the app ID, the user, and the user's role with a tenant. The content of the response depends on the context in which the app is calling; for details, see the scenarios in the Permissions section.
      externalDocs:
        description: Find more info here
        url: https://learn.microsoft.com/graph/api/subscription-list?view=graph-rest-1.0
      operationId: subscription_ListSubscription
      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.subscriptionCollectionResponse'
        default:
          $ref: '#/components/responses/error'
      x-ms-pageable:
        nextLinkName: '@odata.nextLink'
        operationName: listMore
      x-ms-docs-operation-type: operation
    post:
      tags:
      - Subscriptions subscription
      summary: Create subscription
      description: 'Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph. To identify the resources for which you can create subscriptions and the limitations on subscriptions, see Set up notifications for changes in resource data: Supported resources. Some resources support rich notifications, that is, notifications that include resource data. For more information about these resources, see Set up change notifications that include resource data: Supported resources.'
      externalDocs:
        description: Find more info here
        url: https://learn.microsoft.com/graph/api/subscription-post-subscriptions?view=graph-rest-1.0
      operationId: subscription_CreateSubscription
      requestBody:
        description: New entity
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/microsoft.graph.subscription'
        required: true
      responses:
        2XX:
          description: Created entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/microsoft.graph.subscription'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  /subscriptions/{subscription-id}:
    get:
      tags:
      - Subscriptions subscription
      summary: Get subscription
      description: Retrieve the properties and relationships of a subscription. See the table in the Permissions section for the list of resources that support subscribing to change notifications.
      externalDocs:
        description: Find more info here
        url: https://learn.microsoft.com/graph/api/subscription-get?view=graph-rest-1.0
      operationId: subscription_GetSubscription
      parameters:
      - name: subscription-id
        in: path
        description: The unique identifier of subscription
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: subscription
      - name: $select
        in: query
        description: Select properties to be returned
        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.subscription'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    patch:
      tags:
      - Subscriptions subscription
      summary: Update subscription
      description: Renew a subscription by extending its expiry time. The table in the Permissions section lists the resources that support subscribing to change notifications. Subscriptions expire after a length of time that varies by resource type. In order to avoid missing change notifications, an app should renew its subscriptions well in advance of their expiry date. See subscription for maximum length of a subscription for each resource type.
      externalDocs:
        description: Find more info here
        url: https://learn.microsoft.com/graph/api/subscription-update?view=graph-rest-1.0
      operationId: subscription_UpdateSubscription
      parameters:
      - name: subscription-id
        in: path
        description: The unique identifier of subscription
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: subscription
      requestBody:
        description: New property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/microsoft.graph.subscription'
        required: true
      responses:
        2XX:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/microsoft.graph.subscription'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    delete:
      tags:
      - Subscriptions subscription
      summary: Delete subscription
      description: Delete a subscription. For the list of resources that support subscribing to change notifications, see the table in the Permissions section.
      externalDocs:
        description: Find more info here
        url: https://learn.microsoft.com/graph/api/subscription-delete?view=graph-rest-1.0
      operationId: subscription_DeleteSubscription
      parameters:
      - name: subscription-id
        in: path
        description: The unique identifier of subscription
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: subscription
      - name: If-Match
        in: header
        description: ETag
        style: simple
        schema:
          type: string
      responses:
        2XX:
          description: Success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
components:
  responses:
    error:
      description: error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/microsoft.graph.ODataErrors.ODataError'
    microsoft.graph.subscriptionCollectionResponse:
      description: Retrieved collection
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/microsoft.graph.subscriptionCollectionResponse'
  schemas:
    microsoft.graph.ODataErrors.MainError:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
          x-ms-primary-error-message: true
        target:
          type:
          - string
          - 'null'
        details:
          type: array
          items:
            $ref: '#/components/schemas/microsoft.graph.ODataErrors.ErrorDetails'
        innerError:
          $ref: '#/components/schemas/microsoft.graph.ODataErrors.InnerError'
      additionalProperties:
        type: object
    microsoft.graph.ODataErrors.ODataError:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/microsoft.graph.ODataErrors.MainError'
      additionalProperties:
        type: object
    microsoft.graph.entity:
      title: entity
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for an entity. Read-only.
      additionalProperties:
        type: object
    microsoft.graph.subscriptionCollectionResponse:
      title: Collection of subscription
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/microsoft.graph.subscription'
        '@odata.nextLink':
          type:
          - string
          - 'null'
      additionalProperties:
        type: object
    microsoft.graph.subscription:
      allOf:
      - $ref: '#/components/schemas/microsoft.graph.entity'
      - title: subscription
        type: object
        properties:
          applicationId:
            type:
            - string
            - 'null'
            description: Optional. Identifier of the application used to create the subscription. Read-only.
          changeType:
            type: string
            description: 'Required. Indicates the type of change in the subscribed resource that raises a change notification. The supported values are: created, updated, deleted. Multiple values can be combined using a comma-separated list. Note:  Drive root item and list change notifications support only the updated changeType. User and group change notifications support updated and deleted changeType. Use updated to receive notifications when user or group is created, updated, or soft deleted. Use deleted to receive notifications when user or group is permanently deleted.'
          clientState:
            type:
            - string
            - 'null'
            description: Optional. Specifies the value of the clientState property sent by the service in each change notification. The maximum length is 128 characters. The client can check that the change notification came from the service by comparing the value of the clientState property sent with the subscription with the value of the clientState property received with each change notification.
          creatorId:
            type:
            - string
            - 'null'
            description: Optional. Identifier of the user or service principal that created the subscription. If the app used delegated permissions to create the subscription, this field contains the ID of the signed-in user the app called on behalf of. If the app used application permissions, this field contains the ID of the service principal corresponding to the app. Read-only.
          encryptionCertificate:
            type:
            - string
            - 'null'
            description: Optional. A base64-encoded representation of a certificate with a public key used to encrypt resource data in change notifications. Optional but required when includeResourceData is true.
          encryptionCertificateId:
            type:
            - string
            - 'null'
            description: Optional. A custom app-provided identifier to help identify the certificate needed to decrypt resource data.
          expirationDateTime:
            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: Required. Specifies the date and time when the webhook subscription expires. The time is in UTC, and can be an amount of time from subscription creation that varies for the resource subscribed to. Any value under 45 minutes after the time of the request is automatically set to 45 minutes after the request time. For the maximum supported subscription length of time, see Subscription lifetime.
            format: date-time
          includeResourceData:
            type:
            - boolean
            - 'null'
            description: Optional. When set to true, change notifications include resource data (such as content of a chat message).
          latestSupportedTlsVersion:
            type:
            - string
            - 'null'
            description: 'Optional. Specifies the latest version of Transport Layer Security (TLS) that the notification endpoint, specified by notificationUrl, supports. The possible values are: v10, v11, v12, v13. For subscribers whose notification endpoint supports a version lower than the currently recommended version (TLS 1.2), specifying this property by a set timeline allows them to temporarily use their deprecated version of TLS before completing their upgrade to TLS 1.2. For these subscribers, not setting this property per the timeline would result in subscription operations failing. For subscribers whose notification endpoint already supports TLS 1.2, setting this property is optional. In such cases, Microsoft Graph defaults the property to v1_2.'
          lifecycleNotificationUrl:
            type:
            - string
            - 'null'
            description: Required for Teams resources if  the expirationDateTime value is more than 1 hour from now; optional otherwise. The URL of the endpoint that receives lifecycle notifications, including subscriptionRemoved, reauthorizationRequired, and missed notifications. This URL must make use of the HTTPS protocol. For more information, see Reduce missing subscriptions and change notifications.
          notificationQueryOptions:
            type:
            - string
            - 'null'
            description: Optional. OData query options for specifying value for the targeting resource. Clients receive notifications when resource reaches the state matching the query options provided here. With this new property in the subscription creation payload along with all existing properties, Webhooks deliver notifications whenever a resource reaches the desired state mentioned in the notificationQueryOptions property. For example, when the print job is completed or when a print job resource isFetchable property value becomes true etc.  Supported only for Universal Print Service. For more information, see Subscribe to change notifications from cloud printing APIs using Microsoft Graph.
          notificationUrl:
            type: string
            description: Required. The URL of the endpoint that receives the change notifications. This URL must make use of the HTTPS protocol. Any query string parameter included in the notificationUrl property is included in the HTTP POST request when Microsoft Graph sends the change notifications.
          notificationUrlAppId:
            type:
            - string
            - 'null'
            description: Optional. The app ID that the subscription service can use to generate the validation token. The value allows the client to validate the authenticity of the notification received.
          resource:
            type: string
            description: Required. Specifies the resource that is monitored for changes. Don't include the base URL (https://graph.microsoft.com/v1.0/). See the possible resource path values for each supported resource.
        additionalProperties:
          type: object
    microsoft.graph.ODataErrors.InnerError:
      type: object
      additionalProperties:
        type: object
      description: The structure of this object is service-specific
    microsoft.graph.ODataErrors.ErrorDetails:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        target:
          type:
          - string
          - 'null'
      additionalProperties:
        type: object
  parameters:
    count:
      name: $count
      in: query
      description: Include count of items
      style: form
      explode: false
      schema:
        type: boolean
    filter:
      name: $filter
      in: query
      description: Filter items by property values
      style: form
      explode: false
      schema:
        type: string
    search:
      name: $search
      in: query
      description: Search items by search phrases
      style: form
      explode: false
      schema:
        type: string
    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
  securitySchemes:
    azureaadv2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes: {}