List subscriptions

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Retrieve a list of webhook subscriptions.

The content of the response depends on the context in which the app is calling; for details, see the scenarios in the Permissions section.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Permissions

Depending on the resource and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. To learn more, including taking caution before choosing more privileged permissions, search for the following permissions in Permissions.

Note

Some resources support change notifications in multiple scenarios, each of which may require different permissions. In those cases, use the resource path to differentiate the scenarios.

Supported resource Delegated (work or school account) Delegated (personal Microsoft account) Application
approvalItems Not supported. Not supported. ApprovalSolution.ReadWrite.All
callRecord Not supported. Not supported. CallRecords.Read.All
callRecording
communications/onlineMeetings/getAllRecordings
Any recording becomes available in the tenant.
Not supported. Not supported. OnlineMeetingRecording.Read.All
callRecording
communications/onlineMeetings/{onlineMeetingId}/recordings
Any recording becomes available for a specific meeting.
OnlineMeetingRecording.Read.All Not supported. OnlineMeetingRecording.Read.All
callRecording
users/{userId}/onlineMeetings/getAllRecordings
A call recording that becomes available in a meeting organized by a specific user.
OnlineMeetingRecording.Read.All Not supported. OnlineMeetingRecording.Read.All
callRecording
appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings
A call recording that becomes available in a meeting where a particular Teams app is installed.
Not supported. Not supported. OnlineMeetingRecording.Read.All, OnlineMeetingRecording.Read.Chat
callTranscript
communications/onlineMeetings/getAllTranscripts
Any transcript becomes available in the tenant.
Not supported. Not supported. OnlineMeetingTranscript.Read.All
callTranscript
communications/onlineMeetings/{onlineMeetingId}/transcripts
Any transcript becomes available for a specific meeting.
OnlineMeetingTranscript.Read.All Not supported. OnlineMeetingTranscript.Read.All
callTranscript
users/{userId}/onlineMeetings/getAllTranscripts
A call transcript that becomes available in a meeting organized by a specific user.
OnlineMeetingTranscript.Read.All Not supported. OnlineMeetingTranscript.Read.All
callTranscript
appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts
A call transcript that becomes available in a meeting where a particular Teams app is installed.
Not supported. Not supported. OnlineMeetingTranscript.Read.All, OnlineMeetingTranscript.Read.Chat
channel
/teams/getAllChannels
All channels in an organization.
Not supported. Not supported. Channel.ReadBasic.All, ChannelSettings.Read.All
channel
/teams/{id}/channels
All channels in a particular team in an organization.
Channel.ReadBasic.All, ChannelSettings.Read.All, Subscription.Read.All Not supported. Channel.ReadBasic.All, ChannelSettings.Read.All
chat
/chats
All chats in an organization.
Not supported. Not supported. Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chat
/chats/{id}
A particular chat.
Chat.ReadBasic, Chat.Read, Chat.ReadWrite, Subscription.Read.All Not supported. ChatSettings.Read.Chat, ChatSettings.ReadWrite.Chat, Chat.Manage.Chat, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chat
/appCatalogs/teamsApps/{id}/installedToChats
All chats in an organization where a particular Teams app is installed.
Not supported. Not supported. Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
chat
/users/{id}/chats
All chats that a particular user is part of.
Chat.ReadBasic, Chat.Read, Chat.ReadWrite Not supported. Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chatMessage
/teams/{id}/channels/{id}/messages
All messages and replies in a particular channel.
ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All, Subscription.Read.All Not supported. ChannelMessage.Read.Group, ChannelMessage.Read.All
chatMessage
/teams/getAllMessages
All channel messages in organization.
Not supported. Not supported. ChannelMessage.Read.All
chatMessage
/chats/{id}/messages
All messages in a chat.
Chat.Read, Chat.ReadWrite, Subscription.Read.All Not supported. Chat.Read.All
chatMessage
/chats/getAllMessages
All chat messages in an organization.
Not supported. Not supported. Chat.Read.All
chatMessage
/users/{id}/chats/getAllMessages
Chat messages for all chats a particular user is part of.
Chat.Read, Chat.ReadWrite, Subscription.Read.All Not supported. Chat.Read.All, Chat.ReadWrite.All
chatMessage
/appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
Chat messages for all chats in an organization where a particular Teams app is installed.
Not supported. Not supported. Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
contact Contacts.Read, Subscription.Read.All Contacts.Read, Subscription.Read.All Contacts.Read
conversationMember
/chats/getAllMembers
Members of all chats in an organization.
Not supported. Not supported. ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember
/chats/{id}/members
Members of a particular chat.
ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite, Subscription.Read.All Not supported. ChatMember.Read.Chat, Chat.Manage.Chat, ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember
appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
Chat members for all chats in an organization where a particular Teams app is installed.
Not supported. Not supported. ChatMember.Read.WhereInstalled, ChatMember.ReadWrite.WhereInstalled, Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
conversationMember
/teams/getAllMembers
Members in all teams in an organization.
Not supported. Not supported. TeamMember.Read.All, TeamMember.ReadWrite.All
conversationMember
/teams/{id}/members
Members in a particular team.
TeamMember.Read.All, Subscription.Read.All Not supported. TeamMember.Read.All
conversationMember
/teams/{id}/channels/getAllMembers
Members in all private channels of a particular team.
Not supported. Not supported. ChannelMember.Read.All
conversationMember
/teams/getAllChannels/getAllMembers
Not supported. Not supported. ChannelMember.Read.All
driveItem
User's personal OneDrive.
Not supported. Files.ReadWrite, Subscription.Read.All Not supported.
driveItem
OneDrive for work or school.
Files.ReadWrite.All, Subscription.Read.All Not supported. Files.ReadWrite.All
event Calendars.Read, Subscription.Read.All Calendars.Read, Subscription.Read.All Calendars.Read
group Group.Read.All, Subscription.Read.All Not supported. Group.Read.All
group conversation Group.Read.All, Subscription.Read.All Not supported. Not supported.
list Sites.ReadWrite.All, Subscription.Read.All Not supported. Sites.ReadWrite.All
message Mail.ReadBasic, Mail.Read, Subscription.Read.All Mail.ReadBasic, Mail.Read, Subscription.Read.All Mail.Read
offerShiftRequest
/teams/{id}/schedule/offerShiftRequests
Changes to any offer shift request in a team.
Schedule.Read.All, Schedule.ReadWrite.All Not supported. Schedule.Read.All, Schedule.ReadWrite.All
online meeting Not supported. Not supported. OnlineMeetings.Read.All, OnlineMeetings.ReadWrite.All
openShiftChangeRequest
/teams/{id}/schedule/openShiftChangeRequests
Changes to any open shift request in a team.
Schedule.Read.All, Schedule.ReadWrite.All Not supported. Schedule.Read.All, Schedule.ReadWrite.All
presence Presence.Read.All, Subscription.Read.All Not supported. Not supported.
printer Not supported. Not supported. Printer.Read.All, Printer.ReadWrite.All
printTaskDefinition Not supported. Not supported. PrintTaskDefinition.ReadWrite.All
security alert SecurityEvents.ReadWrite.All, Subscription.Read.All Not supported. SecurityEvents.ReadWrite.All
shift
/teams/{id}/schedule/shifts
Changes to any shift in a team.
Schedule.Read.All, Schedule.ReadWrite.All Not supported. Schedule.Read.All, Schedule.ReadWrite.All
swapShiftsChangeRequest
/teams/{id}/schedule/swapShiftsChangeRequests
Changes to any swap shift request in a team.
Schedule.Read.All, Schedule.ReadWrite.All Not supported. Schedule.Read.All, Schedule.ReadWrite.All
team
/teams
All teams in an organization.
Not supported. Not supported. Team.ReadBasic.All, TeamSettings.Read.All
team
/teams/{id}
A particular team.
Team.ReadBasic.All, TeamSettings.Read.All, Subscription.Read.All Not supported. Team.ReadBasic.All, TeamSettings.Read.All
timeOffRequest
/teams/{id}/schedule/timeOffRequests
Changes to any time off request in a team.
Schedule.Read.All, Schedule.ReadWrite.All Not supported. Schedule.Read.All, Schedule.ReadWrite.All
todoTask Tasks.ReadWrite, Subscription.Read.All Tasks.ReadWrite, Subscription.Read.All Not supported.
user User.Read.All, Subscription.Read.All User.Read.All User.Read.All
baseTask (deprecated) Tasks.ReadWrite, Subscription.Read.All Tasks.ReadWrite, Subscription.Read.All Not supported.

Note

The following permissions use resource-specific consent:

  • OnlineMeetingRecording.Read.Chat
  • OnlineMeetingTranscript.Read.Chat
  • ChatSettings.Read.Chat
  • ChatSettings.ReadWrite.Chat
  • Chat.Manage.Chat
  • ChannelMessage.Read.Group
  • ChatMember.Read.Chat

Response results are based on the context of the calling app. The following sections describe the common scenarios.

Basic scenarios

Most commonly, an application wants to retrieve subscriptions that it originally created for the currently signed-in user or all users in the directory (work/school accounts). These scenarios don't require any special permissions beyond the ones the app used originally to create its subscriptions.

Context of the calling app Response contains
App is calling on behalf of the signed-in user (delegated permission).
-and-
App has the original permission required to create the subscription.

Note: This scenario applies to both personal Microsoft accounts and work/school accounts.
Subscriptions created by the app for the signed-in user only.
App is calling on behalf of itself (application permission).
-and-
App has the original permission required to create the subscription.

Note: This scenario only applies to work/school accounts.
Subscriptions created by the app for itself or any user in the directory.

Advanced scenarios

In some cases, an app wants to retrieve subscriptions created by other apps. For example, a user wants to see all subscriptions created by any app on their behalf. Or, a Global Administrator who wants to see all subscriptions from all apps in their directory. For such scenarios, a delegated permission Subscription.Read.All is required.

Context of the calling app Response contains
App is calling on behalf of the signed-in user (delegated permission). The user is a non-admin.
-and-
App has the permission Subscription.Read.All

Note: This scenario applies to both personal Microsoft accounts and work/school accounts.
Subscriptions created by any app for the signed-in user only.
App is calling on behalf of the signed-in user (delegated permission). The user is a Global Administrator.
-and-
App has the permission Subscription.Read.All

Note: This scenario only applies to work/school accounts.
Subscriptions created by any app for any user in the directory.

HTTP request

GET /subscriptions

Optional query parameters

This method doesn't support the OData query parameters to help customize the response.

Request headers

Name Type Description
Authorization string Bearer {token}. Required. Learn more about authentication and authorization.

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and a list of subscription objects in the response body.

Example

Request

GET https://graph.microsoft.com/beta/subscriptions

Response

The following example shows the response.

Note: The response shown here might be shortened for readability.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions",
  "value": [
    {
      "id": "0fc0d6db-0073-42e5-a186-853da75fb308",
      "resource": "Users",
      "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
      "changeType": "updated,deleted",
      "clientState": null,
      "notificationUrl": "https://webhookappexample.azurewebsites.net/api/notifications",
      "lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
      "expirationDateTime": "2018-03-12T05:00:00Z",
      "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
      "latestSupportedTlsVersion": "v1_2",
      "encryptionCertificate": "",
      "encryptionCertificateId": "",
      "includeResourceData": false,
      "notificationContentType": "application/json"
    }
  ]
}

Note: the clientState property value is not returned for security purposes.

When a request returns multiple pages of data, the response includes an @odata.nextLink property to help you manage the results. To learn more, see Paging Microsoft Graph data in your app.