Notification subscriptions

Last Update: 3/13/2017

api-version = 3.2-preview

If you haven't already, look at the information on getting started with these APIs.

Manage and query notification subscriptions. A subscription defines the conditions by which a user or team should be notified when an event occurs and where notifications should be sent. A user or group can be the subscriber for a subscription.

Create

Create a new subscription.

POST https://{instance}/_apis/notification/subscriptions?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.notification_write Notifications (write) Provides read/write access to subscriptions and read access to event metadata, including filterable field values.

Request parameters

Name In Type Notes
instance URL string Required. VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
api-version Query string Required. Version of the API to use. This should be set to '3.2-preview' to use this version of the API.
Body NotificationSubscriptionCreateParameters Required. Parameters for creating a new subscription. A subscription defines criteria for matching events and how the subscription's subscriber should be notified about those events.

Response

Type Notes
NotificationSubscription A subscription defines criteria for matching events and how the subscription's subscriber should be notified about those events.

For a user

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/subscriptions?api-version=3.2-preview
Content-Type: application/json
{
  "description": "All changes to work items in the Fabrikam project",
  "filter": {
    "eventType": "ms.vss-work.workitem-changed-event",
    "criteria": {
      "clauses": [],
      "groups": [],
      "maxGroupLevel": 0
    },
    "type": "Expression"
  },
  "channel": {
    "type": "EmailHtml"
  },
  "scope": {
    "id": "19980dff-b50a-463e-ad01-2c93628490ff"
  }
}

Sample response

Status code: 200
{
  "id": "114711",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/114711",
  "description": "All changes to work items in the Fabrikam project",
  "subscriber": {
    "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
    "displayName": "Jamal Hartnett",
    "uniqueName": "fabrikamfiber16@outlook.com"
  },
  "status": "enabled",
  "flags": "none",
  "modifiedDate": "2017-03-13T04:46:13.663Z",
  "lastModifiedBy": {
    "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
    "displayName": "Jamal Hartnett",
    "uniqueName": "fabrikamfiber16@outlook.com"
  },
  "scope": {
    "type": "none",
    "id": "19980dff-b50a-463e-ad01-2c93628490ff"
  },
  "filter": {
    "type": "Expression",
    "criteria": {
      "clauses": [
        {
          "logicalOperator": "",
          "fieldName": "",
          "operator": "=",
          "value": "",
          "index": 1
        }
      ],
      "groups": [],
      "maxGroupLevel": 0
    },
    "eventType": "ms.vss-work.workitem-changed-event"
  },
  "channel": {
    "type": "EmailHtml",
    "useCustomAddress": false
  },
  "_links": {
    "edit": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/_notifications?subscriptionId=114711&publisherId=ms.vss-work.work-event-publisher&action=view"
    }
  },
  "permissions": "view, edit, delete"
}

For a team

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/subscriptions?api-version=3.2-preview
Content-Type: application/json
{
  "description": "A new work item enters our area path",
  "filter": {
    "eventType": "ms.vss-work.workitem-changed-event",
    "criteria": {
      "clauses": [],
      "groups": [],
      "maxGroupLevel": 0
    },
    "type": "Expression"
  },
  "subscriber": {
    "id": "552e2388-e9bb-429e-ad71-c2fef2ad085f"
  },
  "channel": {
    "type": "EmailHtml",
    "address": "myteam@fabrikam.org",
    "useCustomAddress": true
  }
}

Sample response

Status code: 200
{
  "id": "114712",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/114712",
  "description": "A new work item enters our area path",
  "subscriber": {
    "id": "552e2388-e9bb-429e-ad71-c2fef2ad085f",
    "displayName": "[FabrikamCloud]\\Fab",
    "uniqueName": "vstfs:///Classification/TeamProject/3b3ae425-0079-421f-9101-bcf15d6df041\\Fab",
    "isContainer": true
  },
  "status": "enabled",
  "flags": "groupSubscription",
  "modifiedDate": "2017-03-13T04:46:18.027Z",
  "lastModifiedBy": {
    "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
    "displayName": "Jamal Hartnett",
    "uniqueName": "fabrikamfiber16@outlook.com"
  },
  "scope": {
    "type": "none",
    "id": "00000000-0000-636f-6c6c-656374696f6e"
  },
  "filter": {
    "type": "Expression",
    "criteria": {
      "clauses": [
        {
          "logicalOperator": "",
          "fieldName": "",
          "operator": "=",
          "value": "",
          "index": 1
        }
      ],
      "groups": [],
      "maxGroupLevel": 0
    },
    "eventType": "ms.vss-work.workitem-changed-event"
  },
  "channel": {
    "type": "EmailHtml",
    "address": "myteam@fabrikam.org",
    "useCustomAddress": true
  },
  "_links": {},
  "permissions": "view, edit, delete"
}

Get

Get a notification subscription by its ID.

GET https://{instance}/_apis/notification/subscriptions/{subscriptionId}?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.notification Notifications (read) Provides read access to subscriptions and event metadata, including filterable field values.

Request parameters

Name In Type Notes
instance URL string Required. VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
subscriptionId URL string Required.
api-version Query string Required. Version of the API to use. This should be set to '3.2-preview' to use this version of the API.
queryFlags Query SubscriptionQueryFlags Optional.

Response

Type Notes
NotificationSubscription A subscription defines criteria for matching events and how the subscription's subscriber should be notified about those events.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/subscriptions/114711?api-version=3.2-preview

Sample response

Status code: 200
{
  "id": "114711",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/114711",
  "description": "All changes to work items in the Fabrikam project",
  "subscriber": {
    "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
    "displayName": "Jamal Hartnett",
    "uniqueName": "fabrikamfiber16@outlook.com"
  },
  "status": "enabled",
  "flags": "none",
  "modifiedDate": "2017-03-13T04:46:13.663Z",
  "lastModifiedBy": {
    "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
    "displayName": "Jamal Hartnett",
    "uniqueName": "fabrikamfiber16@outlook.com"
  },
  "scope": {
    "type": "none",
    "id": "19980dff-b50a-463e-ad01-2c93628490ff"
  },
  "filter": {
    "type": "Expression",
    "criteria": {
      "clauses": [
        {
          "logicalOperator": "",
          "fieldName": "",
          "operator": "=",
          "value": "",
          "index": 1
        }
      ],
      "groups": [],
      "maxGroupLevel": 0
    },
    "eventType": "ms.vss-work.workitem-changed-event"
  },
  "channel": {
    "type": "EmailHtml",
    "useCustomAddress": false
  },
  "_links": {
    "edit": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/_notifications?subscriptionId=114711&publisherId=ms.vss-work.work-event-publisher&action=view"
    }
  },
  "permissions": "view, edit, delete"
}

Query

Query for subscriptions. A subscription is returned if it matches one or more of the specified conditions.

POST https://{instance}/_apis/notification/subscriptionquery?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.notification Notifications (read) Provides read access to subscriptions and event metadata, including filterable field values.

Request parameters

Name In Type Notes
instance URL string Required. VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
api-version Query string Required. Version of the API to use. This should be set to '3.2-preview' to use this version of the API.
Body SubscriptionQuery Required. Notification subscriptions query input.

Response

Type Notes
VssJsonCollectionWrapper<array (NotificationSubscription)>

By subscriber

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/subscriptionQuery?api-version=3.2-preview
Content-Type: application/json
{
  "conditions": [
    {
      "subscriber": "552e2388-e9bb-429e-ad71-c2fef2ad085f"
    }
  ]
}

Sample response

Status code: 200
{
  "count": 3,
  "value": [
    {
      "id": "105645",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/105645",
      "description": "A pull request is created or updated",
      "subscriber": {
        "id": "552e2388-e9bb-429e-ad71-c2fef2ad085f",
        "displayName": "[FabrikamCloud]\\Fab",
        "uniqueName": "vstfs:///Classification/TeamProject/3b3ae425-0079-421f-9101-bcf15d6df041\\Fab",
        "isContainer": true
      },
      "status": "enabled",
      "flags": "groupSubscription, canOptOut",
      "modifiedDate": "2017-01-10T17:53:24.337Z",
      "lastModifiedBy": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "scope": {
        "type": "none",
        "id": "00000000-0000-636f-6c6c-656374696f6e"
      },
      "filter": {
        "type": "Actor",
        "inclusions": [
          "author",
          "reviewer",
          "changedReviewers"
        ],
        "exclusions": [
          "initiator"
        ],
        "criteria": {
          "clauses": [],
          "groups": [],
          "maxGroupLevel": 0
        },
        "eventType": "ms.vss-code.git-pullrequest-event"
      },
      "channel": {
        "type": "User",
        "useCustomAddress": false
      },
      "adminSettings": {
        "blockUserOptOut": false
      },
      "subscriptionUserSettings": {
        "optedOut": false
      },
      "_links": {},
      "permissions": "view, edit, delete"
    },
    {
      "id": "105936",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/105936",
      "description": "A build completes",
      "subscriber": {
        "id": "552e2388-e9bb-429e-ad71-c2fef2ad085f",
        "displayName": "[FabrikamCloud]\\Fab",
        "uniqueName": "vstfs:///Classification/TeamProject/3b3ae425-0079-421f-9101-bcf15d6df041\\Fab",
        "isContainer": true
      },
      "status": "enabled",
      "flags": "groupSubscription",
      "modifiedDate": "2017-01-25T02:09:42.863Z",
      "lastModifiedBy": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "scope": {
        "type": "none",
        "id": "3b3ae425-0079-421f-9101-bcf15d6df041"
      },
      "filter": {
        "type": "Expression",
        "eventType": "ms.vss-build.build-completed-event"
      },
      "channel": {
        "type": "EmailHtml",
        "address": "tasd@boo.com",
        "useCustomAddress": true
      },
      "_links": {},
      "permissions": "view, edit, delete"
    },
    {
      "id": "114712",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/114712",
      "description": "A new work item enters our area path",
      "subscriber": {
        "id": "552e2388-e9bb-429e-ad71-c2fef2ad085f",
        "displayName": "[FabrikamCloud]\\Fab",
        "uniqueName": "vstfs:///Classification/TeamProject/3b3ae425-0079-421f-9101-bcf15d6df041\\Fab",
        "isContainer": true
      },
      "status": "enabled",
      "flags": "groupSubscription",
      "modifiedDate": "2017-03-13T04:46:18.027Z",
      "lastModifiedBy": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "scope": {
        "type": "none",
        "id": "00000000-0000-636f-6c6c-656374696f6e"
      },
      "filter": {
        "type": "Expression",
        "eventType": "ms.vss-work.workitem-changed-event"
      },
      "channel": {
        "type": "EmailHtml",
        "address": "myteam@fabrikam.org",
        "useCustomAddress": true
      },
      "_links": {},
      "permissions": "view, edit, delete"
    }
  ]
}

List

Get a list of subscriptions. If no subscriber is specified, subscriptions for the calling user are returned.

GET https://{instance}/_apis/notification/subscriptions?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.notification Notifications (read) Provides read access to subscriptions and event metadata, including filterable field values.

Request parameters

Name In Type Notes
instance URL string Required. VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
api-version Query string Required. Version of the API to use. This should be set to '3.2-preview' to use this version of the API.
subscriber Query GUID Optional.
queryFlags Query SubscriptionQueryFlags Optional.

Response

Type Notes
VssJsonCollectionWrapper<array (NotificationSubscription)>

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/subscriptions?api-version=3.2-preview

Sample response

Status code: 200
{
  "count": 4,
  "value": [
    {
      "id": "105852",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/105852",
      "description": "A commit is pushed by me",
      "subscriber": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "status": "enabled",
      "flags": "none",
      "modifiedDate": "2017-01-04T16:14:15.487Z",
      "lastModifiedBy": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "scope": {
        "type": "none",
        "id": "473139fc-10c2-419d-ad16-d18610b76be3"
      },
      "filter": {
        "type": "Expression",
        "criteria": {
          "clauses": [
            {
              "logicalOperator": "",
              "fieldName": "Pushed by",
              "operator": "=",
              "value": "[Me]",
              "index": 1
            }
          ],
          "groups": [],
          "maxGroupLevel": 0
        },
        "eventType": "ms.vss-code.git-push-event"
      },
      "channel": {
        "type": "EmailHtml",
        "useCustomAddress": false
      },
      "_links": {
        "edit": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/_notifications?subscriptionId=105852&publisherId=ms.vss-code.git-event-publisher&action=view"
        }
      },
      "permissions": "view, edit, delete"
    },
    {
      "id": "105897",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/105897",
      "description": "Code is pushed to the Ops repo",
      "subscriber": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "status": "disabled",
      "flags": "none",
      "modifiedDate": "2017-01-07T20:49:54.307Z",
      "lastModifiedBy": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "scope": {
        "type": "none",
        "id": "00000000-0000-636f-6c6c-656374696f6e"
      },
      "filter": {
        "type": "Expression",
        "criteria": {
          "clauses": [
            {
              "logicalOperator": "",
              "fieldName": "Pushed by",
              "operator": "=",
              "value": "[Me]",
              "index": 1
            }
          ],
          "groups": [],
          "maxGroupLevel": 0
        },
        "eventType": "ms.vss-code.git-push-event"
      },
      "channel": {
        "type": "EmailHtml",
        "useCustomAddress": false
      },
      "_links": {
        "edit": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/_notifications?subscriptionId=105897&publisherId=ms.vss-code.git-event-publisher&action=view"
        }
      },
      "permissions": "view, edit, delete"
    },
    {
      "id": "114710",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/114710",
      "description": "All changes to work items in the Fabrikam project",
      "subscriber": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "status": "enabled",
      "flags": "none",
      "modifiedDate": "2017-03-13T04:45:51.343Z",
      "lastModifiedBy": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "scope": {
        "type": "none",
        "id": "19980dff-b50a-463e-ad01-2c93628490ff"
      },
      "filter": {
        "type": "Expression",
        "criteria": {
          "clauses": [
            {
              "logicalOperator": "",
              "fieldName": "",
              "operator": "=",
              "value": "",
              "index": 1
            }
          ],
          "groups": [],
          "maxGroupLevel": 0
        },
        "eventType": "ms.vss-work.workitem-changed-event"
      },
      "channel": {
        "type": "EmailHtml",
        "useCustomAddress": false
      },
      "_links": {
        "edit": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/_notifications?subscriptionId=114710&publisherId=ms.vss-work.work-event-publisher&action=view"
        }
      },
      "permissions": "view, edit, delete"
    },
    {
      "id": "114711",
      "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/114711",
      "description": "All changes to work items in the Fabrikam project",
      "subscriber": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "status": "enabled",
      "flags": "none",
      "modifiedDate": "2017-03-13T04:46:13.663Z",
      "lastModifiedBy": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "scope": {
        "type": "none",
        "id": "19980dff-b50a-463e-ad01-2c93628490ff"
      },
      "filter": {
        "type": "Expression",
        "criteria": {
          "clauses": [
            {
              "logicalOperator": "",
              "fieldName": "",
              "operator": "=",
              "value": "",
              "index": 1
            }
          ],
          "groups": [],
          "maxGroupLevel": 0
        },
        "eventType": "ms.vss-work.workitem-changed-event"
      },
      "channel": {
        "type": "EmailHtml",
        "useCustomAddress": false
      },
      "_links": {
        "edit": {
          "href": "https://fabrikam-fiber-inc.visualstudio.com/_notifications?subscriptionId=114711&publisherId=ms.vss-work.work-event-publisher&action=view"
        }
      },
      "permissions": "view, edit, delete"
    }
  ]
}

Update

Update an existing subscription. Depending on the type of subscription and permissions, the caller can update the description, filter settings, channel (delivery) settings and more.

PATCH https://{instance}/_apis/notification/subscriptions/{subscriptionId}?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.notification_write Notifications (write) Provides read/write access to subscriptions and read access to event metadata, including filterable field values.

Request parameters

Name In Type Notes
instance URL string Required. VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
subscriptionId URL string Required.
api-version Query string Required. Version of the API to use. This should be set to '3.2-preview' to use this version of the API.
Body NotificationSubscriptionUpdateParameters Required. Parameters for updating an existing subscription. A subscription defines criteria for matching events and how the subscription's subscriber should be notified about those events. Note: only the fields to be updated should be set.

Response

Type Notes
NotificationSubscription A subscription defines criteria for matching events and how the subscription's subscriber should be notified about those events.

Change description

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/subscriptions/114711?api-version=3.2-preview
Content-Type: application/json
{
  "description": "All changes to work items in this account",
  "scope": {
    "id": null
  }
}

Sample response

Status code: 200
{
  "id": "114711",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/114711",
  "description": "All changes to work items in this account",
  "subscriber": {
    "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
    "displayName": "Jamal Hartnett",
    "uniqueName": "fabrikamfiber16@outlook.com"
  },
  "status": "enabled",
  "flags": "none",
  "modifiedDate": "2017-03-13T04:46:15.21Z",
  "lastModifiedBy": {
    "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
    "displayName": "Jamal Hartnett",
    "uniqueName": "fabrikamfiber16@outlook.com"
  },
  "scope": {
    "type": "none",
    "id": "00000000-0000-636f-6c6c-656374696f6e"
  },
  "filter": {
    "type": "Expression",
    "criteria": {
      "clauses": [
        {
          "logicalOperator": "",
          "fieldName": "",
          "operator": "=",
          "value": "",
          "index": 1
        }
      ],
      "groups": [],
      "maxGroupLevel": 0
    },
    "eventType": "ms.vss-work.workitem-changed-event"
  },
  "channel": {
    "type": "EmailHtml",
    "useCustomAddress": false
  },
  "_links": {
    "edit": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/_notifications?subscriptionId=114711&publisherId=ms.vss-work.work-event-publisher&action=view"
    }
  },
  "permissions": "view, edit, delete"
}

Disable

Sample request

PATCH https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/subscriptions/114711?api-version=3.2-preview
Content-Type: application/json
{
  "status": "disabled"
}

Sample response

Status code: 200
{
  "id": "114711",
  "url": "https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/Subscriptions/114711",
  "description": "All changes to work items in this account",
  "subscriber": {
    "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
    "displayName": "Jamal Hartnett",
    "uniqueName": "fabrikamfiber16@outlook.com"
  },
  "status": "disabled",
  "flags": "none",
  "modifiedDate": "2017-03-13T04:46:15.743Z",
  "lastModifiedBy": {
    "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
    "displayName": "Jamal Hartnett",
    "uniqueName": "fabrikamfiber16@outlook.com"
  },
  "scope": {
    "type": "none",
    "id": "00000000-0000-636f-6c6c-656374696f6e"
  },
  "filter": {
    "type": "Expression",
    "criteria": {
      "clauses": [
        {
          "logicalOperator": "",
          "fieldName": "",
          "operator": "=",
          "value": "",
          "index": 1
        }
      ],
      "groups": [],
      "maxGroupLevel": 0
    },
    "eventType": "ms.vss-work.workitem-changed-event"
  },
  "channel": {
    "type": "EmailHtml",
    "useCustomAddress": false
  },
  "_links": {
    "edit": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/_notifications?subscriptionId=114711&publisherId=ms.vss-work.work-event-publisher&action=view"
    }
  },
  "permissions": "view, edit, delete"
}

Delete

Delete a subscription.

DELETE https://{instance}/_apis/notification/subscriptions/{subscriptionId}?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.notification_write Notifications (write) Provides read/write access to subscriptions and read access to event metadata, including filterable field values.

Request parameters

Name In Type Notes
instance URL string Required. VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
subscriptionId URL string Required.
api-version Query string Required. Version of the API to use. This should be set to '3.2-preview' to use this version of the API.

Sample request

DELETE https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/subscriptions/114711?api-version=3.2-preview

Sample response

Status code: 204

Update subscription user settings

Update the specified users' settings for the specified subscription. User settings can only be applied to shared subscriptions, like team subscriptions or default subscriptions. This API is typically used to opt in or out of a shared subscription.

PUT https://{instance}/_apis/notification/Subscriptions/{subscriptionId}/usersettings/{userId}?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.notification_write Notifications (write) Provides read/write access to subscriptions and read access to event metadata, including filterable field values.

Request parameters

Name In Type Notes
instance URL string Required. VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
subscriptionId URL string Required.
userId URL string Required. ID of the user or "me" to indicate the calling user
api-version Query string Required. Version of the API to use. This should be set to '3.2-preview' to use this version of the API.
Body SubscriptionUserSettings Required. User-managed settings for a group subscription.

Response

Type Notes
SubscriptionUserSettings User-managed settings for a group subscription.

Opt out

Sample request

PUT https://fabrikam-fiber-inc.visualstudio.com/_apis/notification/subscriptions/ms.vss-code.pull-request-updated-subscription/userSettings/me?api-version=3.2-preview
Content-Type: application/json
{
  "optedOut": true
}

Sample response

Status code: 200
{
  "optedOut": true
}