Approvals - Query

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

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

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

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.

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.