Approvals - Query

Reference

Service:: Approvals And Checks

API Version:: 7.1-preview.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-preview.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-preview.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-preview.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-preview.1

Sample Response

Status code:: 200

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

Response Body

{
  "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

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 on which approval got created.
executionOrder	ApprovalExecutionOrder	Order in which approvers will be actionable.
id	string	Unique identifier of the approval.
instructions	string	Instructions for the approvers.
lastModifiedOn	string	Date on which approval was last modified.
minRequiredApprovers	integer	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

Include these additional details in the returned objects.

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

ApprovalExecutionOrder

Order in which approvers will be actionable.

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

ApprovalPermissions

Current user permissions for approval object.

Name	Type	Description
none	string
queueBuild	string
reassign	string
resourceAdmin	string
update	string
view	string

ApprovalStatus

Overall status of the approval.

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

ApprovalStep

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	Timestamp at which this step was initiated.
lastModifiedBy	IdentityRef	Identity by which this step was last modified.
lastModifiedOn	string	Timestamp at which this step was last modified.
order	integer	Order in which the approvers are allowed to approve.
permissions	ApprovalPermissions	Current user permissions for step.
status	ApprovalStatus	Current status of this step.

ApprovalStepHistory

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	Timestamp at which this step history was created.

IdentityRef

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

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.