Create subscription

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.

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.

This API is available in the following national cloud deployments.

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

Permissions

Creating a subscription requires read permission to the resource. For example, to get change notifications on messages, your app needs the Mail.Read 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 the permissions, search for the following permissions in Permissions.

Note

• Due to security restrictions, Microsoft Graph subscriptions do not support write access permissions when only read access permissions are needed.
• 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	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	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	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	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	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	Contacts.Read	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	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	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	Not supported.
driveItem (OneDrive for work or school)	Files.ReadWrite.All	Not supported.	Files.ReadWrite.All
event	Calendars.Read	Calendars.Read	Calendars.Read
group	Group.Read.All	Not supported.	Group.Read.All
group conversation	Group.Read.All	Not supported.	Not supported.
list	Sites.ReadWrite.All	Not supported.	Sites.ReadWrite.All
message	Mail.ReadBasic, Mail.Read	Mail.ReadBasic, Mail.Read	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
onlineMeeting	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	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	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	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	Tasks.ReadWrite	Not supported.
user	User.Read.All	User.Read.All	User.Read.All
virtualEventWebinar	VirtualEvent.Read	Not supported.	VirtualEvent.Read.All
baseTask (deprecated)	Tasks.ReadWrite	Tasks.ReadWrite	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

chatMessage

chatMessage subscriptions can be specified to include resource data. If specified to include resource data (includeResourceData set to true), encryption is required. The subscription creation fails if an encryptionCertificate isn't specified for such subscriptions.

You must use the Prefer: include-unknown-enum-members request header to get the following values in chatMessage messageType evolvable enum: systemEventMessage for /teams/{id}/channels/{id}/messages and /chats/{id}/messages resource.

Note

/teams/getAllMessages, /chats/getAllMessages, /me/chats/getAllMessages, /users/{id}/chats/getAllMessages, and /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages are metered APIs; payment models and licensing requirements may apply. /teams/getAllMessages and /chats/getAllMessages support both model=A and model=B payment models, /me/chats/getAllMessages, /users/{id}/chats/getAllMessages, and /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages support only model=B. If you don't specify a payment model in your query, the default evaluation mode will be used.

Note

To add or change a payment model for a subscribed resource of a change notification, you must create a new change notification subscription with the new payment model; updating an existing change notification does not work.

conversationMember

conversationMember subscriptions can be specified to include resource data. If specified to include resource data (includeResourceData set to true), encryption is required. The subscription creation fails if an encryptionCertificate isn't specified.

Note

/teams/getAllMembers, /chats/getAllMembers, and /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers are metered APIs; payment models and licensing requirements may apply. /teams/getAllMembers and /chats/getAllMembers support both model=A and model=B payment models. /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers supports only model=B. If you don't specify a payment model in your query, the default evaluation mode will be used.

Note

To add or change a payment model for a subscribed resource of a change notification, you must create a new change notification subscription with the new payment model; updating an existing change notification does not work.

team, channel, and chat

team, channel, and chat subscriptions can be specified to include resource data. If specified to include resource data (includeResourceData set to true), encryption is required. The subscription creation fails if an encryptionCertificate isn't specified.

You can use the notifyOnUserSpecificProperties query string parameter when you subscribe to changes in a particular chat or at user level. When you set the query string parameter notifyOnUserSpecificProperties to true during subscription creation, two types of payloads are sent to the subscriber. One type contains user-specific properties, and the other is sent without them. For more information, see Get change notifications for chats using Microsoft Graph.

Note

/appCatalogs/teamsApps/{id}/installedToChats has licensing and payment requirements, specifically supporting only model=B. If no model is specified, evaluation mode will be used.

Note

To add or change a payment model for a subscribed resource of a change notification, you must create a new change notification subscription with the new payment model; updating an existing change notification does not work.

Request example

Specify the model query parameter in the resource property in the request body.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "chats/getAllMessages?model=A",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

driveItem

More limitations apply to 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 work or school, you can subscribe to only the root folder. Change notifications are sent for the requested changes on the subscribed folder or any file, folder, or other driveItem instances in its hierarchy. You can't subscribe to drive or driveItem instances that aren't folders, such as individual files.

OneDrive for work or school and SharePoint support sending your application notifications of security events that occur on a driveItem. To subscribe to these events, add the prefer:includesecuritywebhooks header to your request to create a subscription. After the subscription is created, you will receive notifications when the permissions on an item change. This header applies to SharePoint and OneDrive for work or school but not consumer OneDrive accounts.

contact, event, and message

You can subscribe to changes in Outlook contact, event, or message resources and optionally specify in the POST request payload whether to include encrypted resource data in notifications.

Creating and managing (getting, updating, and deleting) a subscription requires a read scope to the resource. For example, to get change notifications on messages, your app needs the Mail.Read permission. Outlook change notifications support delegated and application permission scopes. Note the following limitations:

• Delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. For example, you can't 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.
  • Don't 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.

onlineMeetings, presence

Subscriptions on onlineMeetings and presence require the encryptionCertificate and encryptionCertificateId property when creating a subscription for notifications with encrypted resource data. For more information, see setting up change notifications to include resource data. For details about online meeting subscriptions, see Get change notifications for online meetings.

virtualEventWebinar

Subscriptions on virtual events support only basic notifications and are limited to a few entities of a virtual event. For more information about the supported subscription types, see Get change notifications for Microsoft Teams virtual event updates.

HTTP request

POST /subscriptions

Request headers

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

Request body

In the request body, supply a JSON representation of subscription object.

Response

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

For details about how errors are returned, see Error responses.

Example

Request

In the request body, supply a JSON representation of the subscription object. The clientState and latestSupportedTlsVersion fields are optional.

This request creates a subscription for change notifications about new mail received by the currently signed-in user.

HTTP

POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new Subscription
{
	ChangeType = "created",
	NotificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient",
	Resource = "me/mailFolders('Inbox')/messages",
	ExpirationDateTime = DateTimeOffset.Parse("2016-11-20T18:23:45.9356913Z"),
	ClientState = "secretClientValue",
	LatestSupportedTlsVersion = "v1_2",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions.PostAsync(requestBody);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

mgc-beta subscriptions create --body '{\
   "changeType": "created",\
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",\
   "resource": "me/mailFolders('Inbox')/messages",\
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",\
   "clientState": "secretClientValue",\
   "latestSupportedTlsVersion": "v1_2"\
}\
'

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  "time"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewSubscription()
changeType := "created"
requestBody.SetChangeType(&changeType) 
notificationUrl := "https://webhook.azurewebsites.net/api/send/myNotifyClient"
requestBody.SetNotificationUrl(&notificationUrl) 
resource := "me/mailFolders('Inbox')/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2016-11-20T18:23:45.9356913Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "secretClientValue"
requestBody.SetClientState(&clientState) 
latestSupportedTlsVersion := "v1_2"
requestBody.SetLatestSupportedTlsVersion(&latestSupportedTlsVersion) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Subscription subscription = new Subscription();
subscription.setChangeType("created");
subscription.setNotificationUrl("https://webhook.azurewebsites.net/api/send/myNotifyClient");
subscription.setResource("me/mailFolders('Inbox')/messages");
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2016-11-20T18:23:45.9356913Z");
subscription.setExpirationDateTime(expirationDateTime);
subscription.setClientState("secretClientValue");
subscription.setLatestSupportedTlsVersion("v1_2");
Subscription result = graphClient.subscriptions().post(subscription);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
   changeType: 'created',
   notificationUrl: 'https://webhook.azurewebsites.net/api/send/myNotifyClient',
   resource: 'me/mailFolders(\'Inbox\')/messages',
   expirationDateTime: '2016-11-20T18:23:45.9356913Z',
   clientState: 'secretClientValue',
   latestSupportedTlsVersion: 'v1_2'
};

await client.api('/subscriptions')
	.version('beta')
	.post(subscription);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\Subscription;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Subscription();
$requestBody->setChangeType('created');
$requestBody->setNotificationUrl('https://webhook.azurewebsites.net/api/send/myNotifyClient');
$requestBody->setResource('me/mailFolders(\'Inbox\')/messages');
$requestBody->setExpirationDateTime(new \DateTime('2016-11-20T18:23:45.9356913Z'));
$requestBody->setClientState('secretClientValue');
$requestBody->setLatestSupportedTlsVersion('v1_2');

$result = $graphServiceClient->subscriptions()->post($requestBody)->wait();

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Beta.ChangeNotifications

$params = @{
	changeType = "created"
	notificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient"
	resource = "me/mailFolders('Inbox')/messages"
	expirationDateTime = [System.DateTime]::Parse("2016-11-20T18:23:45.9356913Z")
	clientState = "secretClientValue"
	latestSupportedTlsVersion = "v1_2"
}

New-MgBetaSubscription -BodyParameter $params

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.subscription import Subscription
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Subscription(
	change_type = "created",
	notification_url = "https://webhook.azurewebsites.net/api/send/myNotifyClient",
	resource = "me/mailFolders('Inbox')/messages",
	expiration_date_time = "2016-11-20T18:23:45.9356913Z",
	client_state = "secretClientValue",
	latest_supported_tls_version = "v1_2",
)

result = await graph_client.subscriptions.post(request_body)

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

In the request body, supply a JSON representation of the subscription object. The clientState and latestSupportedTlsVersion fields are optional.

Duplicate subscription behavior

Duplicate subscriptions aren't allowed. When a subscription request contains the same values for changeType and resource that an existing subscription contains, the request fails with an HTTP error code 409 Conflict, and the error message Subscription Id <> already exists for the requested combination.

Resources examples

The following are valid values for the resource property.

Resource type	Examples
approvalItems	solution/approval/approvalItems
callRecord	communications/callRecords
callRecording	communications/onlineMeetings/getAllRecordings, communications/onlineMeetings/{onlineMeetingId}/recordings, users/{userId}/onlineMeetings/getAllRecordings, appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings
callTranscript	communications/onlineMeetings/getAllTranscripts, communications/onlineMeetings/{onlineMeetingId}/transcripts, users/{userId}/onlineMeetings/getAllTranscripts, appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts
channel	/teams/getAllChannels, /teams/{id}/channels
chat	/chats, /chats/{id}
chatMessage	chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages
contact	me/contacts
conversationMember	/chats/{id}/members, /chats/getAllMembers, /teams/{id}/members, /teams/getAllMembers, /teams/{id}/channels/getAllMembers
driveItem	me/drive/root
event	me/events
group	groups
group conversation	groups('{id}')/conversations
list	sites/{site-id}/lists/{list-id}
message	me/mailfolders('inbox')/messages, me/messages
onlineMeeting	/communications/onlineMeetings/?$filter=JoinWebUrl eq '{JoinWebUrl}'
presence	/communications/presences/{id} (single user), /communications/presences?$filter=id in ('{id}','{id}',…) (multiple users)
printer	print/printers/{id}/jobs
printTaskDefinition	print/taskDefinitions/{id}/tasks
team	/teams, /teams/{id}
user	users
todoTask	/me/todo/lists/{todoTaskListId}/tasks
security alert	security/alerts?$filter=status eq 'NewAlert'
baseTask (deprecated)	/me/tasks/lists/{Id}/tasks

Note

Any path starting with me can also be used with users/{id} instead of me to target a specific user instead of the current user.

Response

The following example shows the response.

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

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2",
  "notificationContentType": "application/json"
}

Notification endpoint validation

The subscription notification endpoint (specified in the notificationUrl property) must be capable of responding to a validation request as described in Set up notifications for changes in user data. If validation fails, the request to create the subscription returns a 400 Bad Request error.