List subscriptions

Namespace: microsoft.graph

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.

This API is available in the following national cloud deployments.

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

Permissions

This API supports the following permission scopes; to learn more, including how to choose permissions, see Permissions.

Supported resource Delegated (work or school account) Delegated (personal Microsoft account) Application
callRecord (/communications/callRecords) Not supported Not supported CallRecords.Read.All
callRecording
communications/onlineMeetings/getAllRecordings
All recordings in an organization.
Not supported. Not supported. OnlineMeetingRecording.Read.All
callRecording
communications/onlineMeetings/{onlineMeetingId}/recordings
All recordings 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
callTranscript
communications/onlineMeetings/getAllTranscripts
All transcripts in an organization.
Not supported. Not supported. OnlineMeetingTranscript.Read.All
callTranscript
communications/onlineMeetings/{onlineMeetingId}/transcripts
All transcripts 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
channel (/teams/getAllChannels – all channels in an organization) Not supported Not supported Channel.ReadBasic.All, ChannelSettings.Read.All
channel (/teams/{id}/channels) 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}) 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
chatMessage (/teams/{id}/channels/{id}/messages) 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) Chat.Read, Chat.ReadWrite, Subscription.Read.All Not supported Chat.Read.All
chatMessage (/chats/getAllMessages -- all chat messages in 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 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 (/teams/{id}/channels/getAllMembers) Not supported Not supported ChannelMember.Read.All
conversationMember (/chats/getAllMembers) Not supported Not supported ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember (/chats/{id}/members) 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/{id}/members) TeamMember.Read.All, Subscription.Read.All Not supported TeamMember.Read.All
driveItem (user's personal OneDrive) Not supported Files.ReadWrite, Subscription.Read.All Not supported
driveItem (OneDrive for Business) 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
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
team (/teams – all teams in an organization) Not supported Not supported Team.ReadBasic.All, TeamSettings.Read.All
team (/teams/{id}) Team.ReadBasic.All, TeamSettings.Read.All, Subscription.Read.All Not supported Team.ReadBasic.All, TeamSettings.Read.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

Note: Permissions marked with * use resource-specific consent.

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 for 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 applies to both personal Microsoft accounts and work/school accounts.
Subscriptions created by this 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 applies to work/school accounts only.
Subscriptions created by this app for itself or for 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, an administrator may want 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 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 an admin.
-and-
App has the permission Subscription.Read.All

Note: This applies to work/school accounts only.
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.

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/v1.0/subscriptions

Response

Here's an example of 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/v1.0/$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.