Get subscription

• 09/16/2021
• 4 minutes to read
• • J
  • F
  • j
  • R
  • a
  • +10

Namespace: microsoft.graph

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.

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: Permissions marked with * use resource-specific consent.

chatMessage

chatMessage subscriptions with delegated permissions do not support resource data (includeResourceData must be false), and do not require encryption. The only exception is the /users/{id}/chats/getAllMessages resource (only available in beta) which supports resource data regardless of the permission type.

chatMessage subscriptions with application permissions include resource data, and require encryption. The subscription creation fails if an encryptionCertificate isn't specified. Before you can create a chatMessage subscription, you must request access. For details, see Protected APIs in Microsoft Teams.

conversationMember

driveItem

Additional limitations apply for subscriptions on OneDrive items. The limitations apply to creating as well as managing (getting, updating, and deleting) subscriptions.

On a personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. On OneDrive for Business, you can subscribe to only the root folder. Change notifications are sent for the requested types of changes on the subscribed folder, or any file, folder, or other driveItem instances in its hierarchy. You cannot subscribe to drive or driveItem instances that are not folders, such as individual files.

contact, event, and message

Additional limitations apply for subscriptions on Outlook items. The limitations apply to creating as well as managing (getting, updating, and deleting) subscriptions.

• Delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. For example, you cannot use the delegated permission Calendars.Read to subscribe to events in another user’s mailbox.

• To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:

  • Use the corresponding application permission to subscribe to changes of items in a folder or mailbox of any user in the tenant.
  • Do not use the Outlook sharing permissions (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared, and their read/write counterparts), as they do not support subscribing to change notifications on items in shared or delegated folders.

HTTP request

GET /subscriptions/{id}

Optional query parameters

This method supports the OData Query Parameters to help customize the response.

Request headers

Request body

Do not supply a request body for this method.

Response

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

Example

Request

Here is an example of the request.

GET https://graph.microsoft.com/v1.0/subscriptions/{id}

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var subscription = await graphClient.Subscriptions["{subscription-id}"]
	.Request()
	.GetAsync();

const options = {
	authProvider,
};

const client = Client.init(options);

let subscription = await client.api('/subscriptions/{id}')
	.get();

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/subscriptions/{id}"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
	completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

		MSGraphSubscription *subscription = [[MSGraphSubscription alloc] initWithData:data error:&nserror];

}];

[meDataTask execute];

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = graphClient.subscriptions("{id}")
	.buildRequest()
	.get();

Response

Here is an example of the response.

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

{
  "id":"7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource":"me/messages",
  "applicationId" : "string",
  "changeType":"created,updated",
  "clientState":"secretClientValue",
  "notificationUrl":"https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
  "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
  "creatorId": "string",
  "latestSupportedTlsVersion": "v1_2",
  "encryptionCertificate": "",
  "encryptionCertificateId": "",
  "includeResourceData": false,
  "notificationContentType": "application/json"
}