Approvals - Query

Service:: Approvals And Checks

API Version:: 7.1

List Approvals. This can be used to get a set of pending approvals in a pipeline, on an user or for a resource..

GET https://dev.azure.com/{organization}/{project}/_apis/pipelines/approvals?api-version=7.1

With optional parameters:

GET https://dev.azure.com/{organization}/{project}/_apis/pipelines/approvals?approvalIds={approvalIds}&$expand={$expand}&userIds={userIds}&state={state}&top={top}&api-version=7.1

URI Parameters

Name	In	Required	Type	Description
organization	path	True	string	The name of the Azure DevOps organization.
project	path	True	string	Project ID or project name
api-version	query	True	string	Version of the API to use. This should be set to '7.1' to use this version of the api.
$expand	query		ApprovalDetailsExpandParameter	Include these additional details in the returned objects.
approvalIds	query		string (array (uuid))	List of approval Ids to get.
state	query		ApprovalStatus	Approval status. Returns approvals of any status if not provided
top	query		integer (int32)	Maximum number of approvals to get.
userIds	query		string (array (string))	List of user Ids approvals assigned to. Accepts either user Ids or user descriptors.

Responses

Name	Type	Description
200 OK	Approval[]	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.build	Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to receive notifications about build events via service hooks.

Examples

Sample request

HTTP

GET https://dev.azure.com/{organization}/{project}/_apis/pipelines/approvals?approvalIds=ee14f612-6838-43c0-b445-db238ef14153,06239b11-a904-43a1-be6a-0d44026bd121&api-version=7.1

Sample response

Status code:: 200

request-Context: appId=cid-v1:a892bfef-0287-4640-9f5e-cffc90fbcf94
access-Control-Expose-Headers: Request-Context

{
  "count": 2,
  "value": [
    {
      "id": "ee14f612-6838-43c0-b445-db238ef14153",
      "steps": [],
      "status": "pending",
      "createdOn": "2020-11-19T08:14:49.58Z",
      "lastModifiedOn": "2020-11-19T08:14:49.5793622Z",
      "executionOrder": "anyOrder",
      "minRequiredApprovers": 1,
      "blockedApprovers": [],
      "_links": {
        "self": {
          "href": "https://dev.azure.com/fabrikam/d6b3e0ea-8197-4dec-831b-50e2e06ff95f/_apis/pipelines/approvals/ee14f612-6838-43c0-b445-db238ef14153"
        }
      }
    },
    {
      "id": "06239b11-a904-43a1-be6a-0d44026bd121",
      "steps": [],
      "status": "pending",
      "createdOn": "2020-11-19T09:39:35.28Z",
      "lastModifiedOn": "2020-11-19T09:39:35.2806001Z",
      "executionOrder": "anyOrder",
      "minRequiredApprovers": 1,
      "blockedApprovers": [],
      "_links": {
        "self": {
          "href": "https://dev.azure.com/fabrikam/d6b3e0ea-8197-4dec-831b-50e2e06ff95f/_apis/pipelines/approvals/06239b11-a904-43a1-be6a-0d44026bd121"
        }
      }
    }
  ]
}

Definitions

Name	Description
Approval
ApprovalDetailsExpandParameter	Include these additional details in the returned objects.
ApprovalExecutionOrder	Order in which approvers will be actionable.
ApprovalPermissions	Current user permissions for approval object.
ApprovalStatus	Overall status of the approval.
ApprovalStep	Data for a single approval step.
ApprovalStepHistory	Data for a single approval step history.
IdentityRef
ReferenceLinks	The class to represent a collection of REST reference links.

Approval

Object

Name	Type	Description
_links	ReferenceLinks	/// Gets the links to access the approval object.
blockedApprovers	IdentityRef[]	Identities which are not allowed to approve.
createdOn	string (date-time)	Date on which approval got created.
executionOrder	ApprovalExecutionOrder	Order in which approvers will be actionable.
id	string (uuid)	Unique identifier of the approval.
instructions	string	Instructions for the approvers.
lastModifiedOn	string (date-time)	Date on which approval was last modified.
minRequiredApprovers	integer (int32)	Minimum number of approvers that should approve for the entire approval to be considered approved.
permissions	ApprovalPermissions	Current user permissions for approval object.
status	ApprovalStatus	Overall status of the approval.
steps	ApprovalStep[]	List of steps associated with the approval.

ApprovalDetailsExpandParameter

Enumeration

Include these additional details in the returned objects.

Value	Description
none	No additional properties.
steps	Include approval steps associated with the approval.
permissions	Include current user permissions for approval object.

ApprovalExecutionOrder

Enumeration

Order in which approvers will be actionable.

Value	Description
anyOrder	Indicates that the approvers can approve in any order.
inSequence	Indicates that the approvers can only approve in a sequential order(Order in which they were assigned).

ApprovalPermissions

Enumeration

Current user permissions for approval object.

Value	Description
none
view
update
reassign
resourceAdmin
queueBuild

ApprovalStatus

Enumeration

Overall status of the approval.

Value	Description
undefined
uninitiated	Indicates the approval is Uninitiated. Used in case of in sequence order of execution where given approver is not yet actionable.
pending	Indicates the approval is Pending.
approved	Indicates the approval is Approved.
rejected	Indicates the approval is Rejected.
skipped	Indicates the approval is Skipped.
canceled	Indicates the approval is Canceled.
timedOut	Indicates the approval is Timed out.
failed
completed
all

ApprovalStep

Object

Data for a single approval step.

Name	Type	Description
actualApprover	IdentityRef	Identity who approved.
assignedApprover	IdentityRef	Identity who should approve.
comment	string	Comment associated with this step.
history	ApprovalStepHistory[]	History of the approval step
initiatedOn	string (date-time)	Timestamp at which this step was initiated.
lastModifiedBy	IdentityRef	Identity by which this step was last modified.
lastModifiedOn	string (date-time)	Timestamp at which this step was last modified.
order	integer (int32)	Order in which the approvers are allowed to approve.
permissions	ApprovalPermissions	Current user permissions for step.
status	ApprovalStatus	Current status of this step.

ApprovalStepHistory

Object

Data for a single approval step history.

Name	Type	Description
assignedTo	IdentityRef	Identity who was assigned this approval
comment	string	Comment associated with this step history.
createdBy	IdentityRef	Identity by which this step history was created.
createdOn	string (date-time)	Timestamp at which this step history was created.

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.

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.

Share via

Approvals - Query

URI Parameters

Responses

Security

oauth2

Scopes

Examples

Sample request

Sample response

Definitions

Approval

ApprovalDetailsExpandParameter

ApprovalExecutionOrder

ApprovalPermissions

ApprovalStatus

ApprovalStep

ApprovalStepHistory

IdentityRef

ReferenceLinks