Create subscription

Subscribes a listener application to receive notifications when data on the Microsoft Graph changes.


Creating a subscription requires read scope to the resource. For example, to get notifications messages, your app needs the Mail.Read permission. The following table lists the suggested permission needed for each resource. To learn more, including how to choose permissions, see Permissions.

Resource type / Item Permission
Contacts Contacts.Read
Conversations Group.Read.All
Events Calendars.Read
Messages Mail.Read
Groups Group.Read.All
Users User.Read.All
Drive (User's OneDrive) Files.ReadWrite
Drives (SharePoint shared content and drives) Files.ReadWrite.All
Security alert SecurityEvents.ReadWrite.All

Note: The /v1.0 endpoint allows application permissions for most resources. Conversations in a Group and OneDrive drive root items are not supported with application permissions.

HTTP request

POST /subscriptions

Request headers

Name Type Description
Authorization string Bearer {token}. Required.


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



Here is an example of the request to send a notification when the user receives a new mail.

Content-type: application/json

   "changeType": "created,updated",
   "notificationUrl": "",
   "resource": "me/mailFolders('Inbox')/messages",
   "clientState": "secretClientValue"

In the request body, supply a JSON representation of the subscription object. The clientState field is optional.

Resources examples

The following are valid values for the resource property of the subscription:

Resource type Examples
Mail me/mailfolders('inbox')/messages
Contacts me/contacts
Calendars me/events
Users users
Groups groups
Conversations groups('{id}')/conversations
Drives me/drive/root
Security alert security/alerts?$filter=status eq ‘New’

Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

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

  "@odata.context": "$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created,updated",
  "clientState": "secretClientValue",
  "notificationUrl": "",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437"

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.