Subscriptions - Create

Service:

Notification

API Version:

5.1

Create a new subscription.

POST https://{service}dev.azure.com/{organization}/_apis/notification/subscriptions?api-version=5.1

URI Parameters

Name	In	Required	Type	Description
organization	path		string	The name of the Azure DevOps organization.
service	path		string	The service to which this request is directed.
api-version	query	True	string	Version of the API to use. This should be set to '5.1' to use this version of the api.

Request Body

Name	Type	Description
channel	ISubscriptionChannel	Channel for delivering notifications triggered by the new subscription.
description	string	Brief description for the new subscription. Typically describes filter criteria which helps identity the subscription.
filter	ISubscriptionFilter	Matching criteria for the new subscription. ExpressionFilter
scope	SubscriptionScope	The container in which events must be published from in order to be matched by the new subscription. If not specified, defaults to the current host (typically an account or project collection). For example, a subscription scoped to project A will not produce notifications for events published from project B.
subscriber	IdentityRef	User or group that will receive notifications for events matching the subscription's filter criteria. If not specified, defaults to the calling user.

Responses

Name	Type	Description
200 OK	NotificationSubscription	successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name	Description
vso.notification_write	Provides read/write access to subscriptions and read access to event metadata, including filterable field values.

Examples

Create a personal subscription

Create a team subscription

Subscribe to pull request changes

Subscribe to work item changes

Create a personal subscription

Sample request

HTTP

POST https://dev.azure.com/fabrikam/_apis/notification/subscriptions?api-version=5.1

{
  "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://dev.azure.com/fabrikam/_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://dev.azure.com/fabrikam/_notifications?subscriptionId=114711&publisherId=ms.vss-work.work-event-publisher&action=view"
    }
  },
  "permissions": "view, edit, delete"
}

Create a team subscription

Sample request

HTTP

POST https://dev.azure.com/fabrikam/_apis/notification/subscriptions?api-version=5.1

{
  "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://dev.azure.com/fabrikam/_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"
}

Subscribe to pull request changes

Sample request

HTTP

POST https://dev.azure.com/fabrikam/_apis/notification/subscriptions?api-version=5.1

{
  "filter": {
    "type": "Artifact",
    "artifactType": "PullRequestId",
    "artifactId": "f98fdd10-72fb-4676-b5b7-9afe4f51469d/e8cf478f-d3bb-4629-92a5-91169f5ccedb/1"
  }
}

Sample response

Status code:

200

Subscribe to work item changes

Sample request

HTTP

POST https://dev.azure.com/fabrikam/_apis/notification/subscriptions?api-version=5.1

{
  "filter": {
    "type": "Artifact",
    "artifactType": "WorkItem",
    "artifactId": "1064327"
  }
}

Sample response

Status code:

200

Definitions

Name	Description
IdentityRef
ISubscriptionChannel
ISubscriptionFilter
NotificationSubscription	A subscription defines criteria for matching events and how the subscription's subscriber should be notified about those events.
NotificationSubscriptionCreateParameters	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.
ReferenceLinks	The class to represent a collection of REST reference links.
SubscriptionAdminSettings	Admin-managed settings for a group subscription.
SubscriptionDiagnostics	Contains all the diagnostics settings for a subscription.
SubscriptionFlags	Read-only indicators that further describe the subscription.
SubscriptionPermissions	The permissions the user have for this subscriptions.
SubscriptionScope	A resource, typically an account or project, in which events are published from.
SubscriptionStatus	Status of the subscription. Typically indicates whether the subscription is enabled or not.
SubscriptionTracing	Data controlling a single diagnostic setting for a subscription.
SubscriptionUserSettings	User-managed settings for a group subscription.

IdentityRef

Object

Name	Type	Description
_links	ReferenceLinks	This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
descriptor	string	The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
directoryAlias	string	Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary
displayName	string	This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
id	string
imageUrl	string	Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary
inactive	boolean	Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary
isAadIdentity	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType)
isContainer	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType)
isDeletedInOrigin	boolean
profileUrl	string	Deprecated - not in use in most preexisting implementations of ToIdentityRef
uniqueName	string	Deprecated - use Domain+PrincipalName instead
url	string	This url is the full route to the source resource of this graph subject.

ISubscriptionChannel

Object

Name	Type	Description
type	string

ISubscriptionFilter

Object

Name	Type	Description
eventType	string
type	string

NotificationSubscription

Object

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

Name	Type	Description
_links	ReferenceLinks	Links to related resources, APIs, and views for the subscription.
adminSettings	SubscriptionAdminSettings	Admin-managed settings for the subscription. Only applies when the subscriber is a group.
channel	ISubscriptionChannel	Channel for delivering notifications triggered by the subscription.
description	string	Description of the subscription. Typically describes filter criteria which helps identity the subscription.
diagnostics	SubscriptionDiagnostics	Diagnostics for this subscription.
extendedProperties	object	Any extra properties like detailed description for different contexts, user/group contexts
filter	ISubscriptionFilter	Matching criteria for the subscription. ExpressionFilter
flags	SubscriptionFlags	Read-only indicators that further describe the subscription.
id	string	Subscription identifier.
lastModifiedBy	IdentityRef	User that last modified (or created) the subscription.
modifiedDate	string (date-time)	Date when the subscription was last modified. If the subscription has not been updated since it was created, this value will indicate when the subscription was created.
permissions	SubscriptionPermissions	The permissions the user have for this subscriptions.
scope	SubscriptionScope	The container in which events must be published from in order to be matched by the subscription. If empty, the scope is the current host (typically an account or project collection). For example, a subscription scoped to project A will not produce notifications for events published from project B.
status	SubscriptionStatus	Status of the subscription. Typically indicates whether the subscription is enabled or not.
statusMessage	string	Message that provides more details about the status of the subscription.
subscriber	IdentityRef	User or group that will receive notifications for events matching the subscription's filter criteria.
url	string	REST API URL of the subscriotion.
userSettings	SubscriptionUserSettings	User-managed settings for the subscription. Only applies when the subscriber is a group. Typically used to indicate whether the calling user is opted in or out of a group subscription.

NotificationSubscriptionCreateParameters

Object

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.

Name	Type	Description
channel	ISubscriptionChannel	Channel for delivering notifications triggered by the new subscription.
description	string	Brief description for the new subscription. Typically describes filter criteria which helps identity the subscription.
filter	ISubscriptionFilter	Matching criteria for the new subscription. ExpressionFilter
scope	SubscriptionScope	The container in which events must be published from in order to be matched by the new subscription. If not specified, defaults to the current host (typically an account or project collection). For example, a subscription scoped to project A will not produce notifications for events published from project B.
subscriber	IdentityRef	User or group that will receive notifications for events matching the subscription's filter criteria. If not specified, defaults to the calling user.

ReferenceLinks

Object

The class to represent a collection of REST reference links.

Name	Type	Description
links	object	The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

SubscriptionAdminSettings

Object

Admin-managed settings for a group subscription.

Name	Type	Description
blockUserOptOut	boolean	If true, members of the group subscribed to the associated subscription cannot opt (choose not to get notified)

SubscriptionDiagnostics

Object

Contains all the diagnostics settings for a subscription.

Name	Type	Description
deliveryResults	SubscriptionTracing	Diagnostics settings for retaining delivery results. Used for Service Hooks subscriptions.
deliveryTracing	SubscriptionTracing	Diagnostics settings for troubleshooting notification delivery.
evaluationTracing	SubscriptionTracing	Diagnostics settings for troubleshooting event matching.

SubscriptionFlags

Enumeration

Read-only indicators that further describe the subscription.

Value	Description
none	None
groupSubscription	Subscription's subscriber is a group, not a user
contributedSubscription	Subscription is contributed and not persisted. This means certain fields of the subscription, like Filter, are read-only.
canOptOut	A user that is member of the subscription's subscriber group can opt in/out of the subscription.
teamSubscription	If the subscriber is a group, is it a team.
oneActorMatches	For role based subscriptions, there is an expectation that there will always be at least one actor that matches

SubscriptionPermissions

Enumeration

The permissions the user have for this subscriptions.

Value	Description
none	None
view	full view of description, filters, etc. Not limited.
edit	update subscription
delete	delete subscription

SubscriptionScope

Object

A resource, typically an account or project, in which events are published from.

Name	Type	Description
id	string (uuid)	Required: This is the identity of the scope for the type.
name	string	Optional: The display name of the scope
type	string	Required: The event specific type of a scope.

SubscriptionStatus

Enumeration

Status of the subscription. Typically indicates whether the subscription is enabled or not.

Value	Description
jailedByNotificationsVolume	Subscription is disabled because it generated a high volume of notifications.
pendingDeletion	Subscription is disabled and will be deleted.
disabledArgumentException	Subscription is disabled because of an Argument Exception while processing the subscription
disabledProjectInvalid	Subscription is disabled because the project is invalid
disabledMissingPermissions	Subscription is disabled because the identity does not have the appropriate permissions
disabledFromProbation	Subscription is disabled service due to failures.
disabledInactiveIdentity	Subscription is disabled because the identity is no longer active
disabledMessageQueueNotSupported	Subscription is disabled because message queue is not supported.
disabledMissingIdentity	Subscription is disabled because its subscriber is unknown.
disabledInvalidRoleExpression	Subscription is disabled because it has an invalid role expression.
disabledInvalidPathClause	Subscription is disabled because it has an invalid filter expression.
disabledAsDuplicateOfDefault	Subscription is disabled because it is a duplicate of a default subscription.
disabledByAdmin	Subscription is disabled by an administrator, not the subscription's subscriber.
disabled	Subscription is disabled, typically by the owner of the subscription, and will not produce any notifications.
enabled	Subscription is active.
enabledOnProbation	Subscription is active, but is on probation due to failed deliveries or other issues with the subscription.

SubscriptionTracing

Object

Data controlling a single diagnostic setting for a subscription.

Name	Type	Description
enabled	boolean	Indicates whether the diagnostic tracing is enabled or not.
endDate	string (date-time)	Trace until the specified end date.
maxTracedEntries	integer (int32)	The maximum number of result details to trace.
startDate	string (date-time)	The date and time tracing started.
tracedEntries	integer (int32)	Trace until remaining count reaches 0.

SubscriptionUserSettings

Object

User-managed settings for a group subscription.

Name	Type	Description
optedOut	boolean	Indicates whether the user will receive notifications for the associated group subscription.