accessReviewInstance resource type

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Note

This is the recommended API for access reviews. The previous version of the access reviews API is deprecated.

Represents a Microsoft Entra access review recurrence. If the parent accessReviewScheduleDefinition is a recurring access review, instances represent each recurrence. A review that doesn't recur will have exactly one instance. Instances also represent each unique group being reviewed in the schedule definition. If a schedule definition reviews multiple groups, each group has a unique instance for each recurrence.

Every accessReviewInstance contains a list of decisions that reviewers can take action on. There's one decision per identity being reviewed.

Methods

Method	Return Type	Description
List accessReviewInstances	accessReviewInstance collection	Get a list of the accessReviewInstance objects and their properties.
Get accessReviewInstance	accessReviewInstance	Read the properties and relationships of an accessReviewInstance object.
Update accessReviewInstance	accessReviewInstance	Update the reviewers of an accessReviewInstance object.
filterByCurrentUser	accessReviewInstance collection	Returns all instances on a given accessReviewScheduleDefinition for which the calling user is the reviewer of one or more decisions.
List contacted reviewers	accessReviewReviewer collection	Get the reviewers who received notifications for an access review instance.
sendReminder	None.	Send a reminder to the reviewers of an accessReviewInstance.
stop	None.	Manually stop an accessReviewInstance.
acceptRecommendations	None.	Allows the calling user to accept the decision recommendation for each NotReviewed accessReviewInstanceDecisionItem that they're the reviewer on for a specific accessReviewInstance.
applyDecisions	None.	Manually apply decisions on an accessReviewInstance.
stopApplyDecisions	None.	Allows the calling user to stop the apply decision action on a specific accessReviewInstance.
batchRecordDecisions	None	Review batches of principals or resources in one call.
resetDecisions	None	Resets all decision items on an instance to notReviewed.
List stages	accessReviewStage collection	Retrieve the stages in a multi-stage access review instance.
List decisions	accessReviewInstanceDecisionItem collection	Get the accessReviewInstanceDecisionItem resources from the decisions navigation property.
List pendingAccessReviewInstances (deprecated)	accessReviewInstance collection.	Get all pending accessReviewInstance resources assigned to the calling user. This method is being deprecated and replaced by filterByCurrentUser.

Properties

Property	Type	Description
endDateTime	DateTimeOffset	DateTime when review instance is scheduled to end. The DatetimeOffset type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z. Supports $select. Read-only.
errors	accessReviewError collection	Collection of errors in an access review instance lifecycle. Read-only.
fallbackReviewers	accessReviewReviewerScope collection	This collection of reviewer scopes is used to define the list of fallback reviewers. These fallback reviewers are notified to take action if no users are found from the list of reviewers specified. This could occur when either the group owner is specified as the reviewer but the group owner doesn't exist, or manager is specified as reviewer but a user's manager doesn't exist. Supports $select.
id	String	Unique identifier of the instance. Supports $select. Read-only.
scope	accessReviewScope	Created based on scope and instanceEnumerationScope at the accessReviewScheduleDefinition level. Defines the scope of users reviewed in a group. Supports $select and $filter (contains only). Read-only.
startDateTime	DateTimeOffset	DateTime when review instance is scheduled to start. May be in the future. The DateTimeOffset type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z. Supports $select. Read-only.
status	String	Specifies the status of an accessReview. Possible values: Initializing, NotStarted, Starting, InProgress, Completing, Completed, AutoReviewing, and AutoReviewed. Supports $select, $orderby, and $filter (eq only). Read-only.
reviewers	accessReviewReviewerScope collection	This collection of access review scopes is used to define who the reviewers are. Supports $select. For examples of options for assigning reviewers, see Assign reviewers to your access review definition using the Microsoft Graph API.

Relationships

Relationship	Type	Description
contactedReviewers	accessReviewReviewer collection	Returns the collection of reviewers who were contacted to complete this review. While the reviewers and fallbackReviewers properties of the accessReviewScheduleDefinition might specify group owners or managers as reviewers, contactedReviewers returns their individual identities. Supports $select. Read-only.
definition	accessReviewScheduleDefinition	There's exactly one accessReviewScheduleDefinition associated with each instance. It's the parent schedule for the instance, where instances are created for each recurrence of a review definition and each group selected to review by the definition.
stages	accessReviewStage collection	If the instance has multiple stages, this returns the collection of stages. A new stage will only be created when the previous stage ends. The existence, number, and settings of stages on a review instance are created based on the accessReviewStageSettings on the parent accessReviewScheduleDefinition.
decisions	accessReviewInstanceDecisionItem collection	Each user reviewed in an accessReviewInstance has a decision item representing if they were approved, denied, or not yet reviewed.

JSON representation

The following JSON representation shows the resource type.

{
 "@odata.type": "#microsoft.graph.accessReviewInstance",
 "id": "string (identifier)",
 "displayName": "string",
 "startDateTime": "string (timestamp)",
 "endDateTime": "string (timestamp)",
 "status": "string",
 "scope": {
    "@odata.type": "microsoft.graph.accessReviewScope"
  },
  "reviewers": [
    {
      "@odata.type": "microsoft.graph.accessReviewReviewerScope"
    }
  ],
  "fallbackReviewers": [
    {
      "@odata.type": "microsoft.graph.accessReviewReviewerScope"
    }
  ],
  "contactedReviewers": [
    {
      "@odata.type": "microsoft.graph.accessReviewReviewer"
    }
  ]
}