access_reviews_definitions_instances

Creates, updates, deletes, gets or lists an access_reviews_definitions_instances resource.

Overview

Name	access_reviews_definitions_instances
Type	Resource
Id	entra_id.identity_governance.access_reviews_definitions_instances

Fields

The following fields are returned by SELECT queries:

get

Retrieved navigation property

Name	Datatype	Description
id	string	The unique identifier for an entity. Read-only.
contactedReviewers	array	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.
decisions	array	Each user reviewed in an accessReviewInstance has a decision item representing if they were approved, denied, or not yet reviewed.
endDateTime	string (date-time)	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. (pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$)
fallbackReviewers	array	This collection of reviewer scopes is used to define the list of fallback reviewers. These fallback reviewers will be 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 does not exist, or manager is specified as reviewer but a user's manager does not exist. Supports $select.
reviewers	array	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.
scope		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.
stages	array	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.
startDateTime	string (date-time)	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. (pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$)
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.

list

Retrieved collection

Name	Datatype	Description
id	string	The unique identifier for an entity. Read-only.
contactedReviewers	array	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.
decisions	array	Each user reviewed in an accessReviewInstance has a decision item representing if they were approved, denied, or not yet reviewed.
endDateTime	string (date-time)	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. (pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$)
fallbackReviewers	array	This collection of reviewer scopes is used to define the list of fallback reviewers. These fallback reviewers will be 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 does not exist, or manager is specified as reviewer but a user's manager does not exist. Supports $select.
reviewers	array	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.
scope		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.
stages	array	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.
startDateTime	string (date-time)	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. (pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$)
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.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	access_review_schedule_definition_id, access_review_instance_id		Read the properties and relationships of an accessReviewInstance object.
list	select	access_review_schedule_definition_id		Get a list of the accessReviewInstance objects and their properties.
insert	insert	access_review_schedule_definition_id
update	update	access_review_schedule_definition_id, access_review_instance_id		Update the properties of an accessReviewInstance object. Only the reviewers and fallbackReviewers properties can be updated but the scope property is also required in the request body. You can only add reviewers to the fallbackReviewers property but can't remove existing fallbackReviewers. To update an accessReviewInstance, it's status must be InProgress.
delete	delete	access_review_schedule_definition_id, access_review_instance_id	If-Match
accept_recommendations	exec	access_review_schedule_definition_id, access_review_instance_id		Allows the acceptance of recommendations on all accessReviewInstanceDecisionItem objects that haven't been reviewed on an accessReviewInstance object for which the calling user is a reviewer.
apply_decisions	exec	access_review_schedule_definition_id, access_review_instance_id		Apply review decisions on an accessReviewInstance if the decisions were not applied automatically because the autoApplyDecisionsEnabled property is false in the review's accessReviewScheduleSettings. The status of the accessReviewInstance must be Completed to call this method.
batch_record_decisions	exec	access_review_schedule_definition_id, access_review_instance_id		Enables reviewers to review all accessReviewInstanceDecisionItem objects in batches by using principalId, resourceId, or neither.
reset_decisions	exec	access_review_schedule_definition_id, access_review_instance_id		Resets all accessReviewInstanceDecisionItem objects on an accessReviewInstance to notReviewed.
send_reminder	exec	access_review_schedule_definition_id, access_review_instance_id		Send a reminder to the reviewers of an active accessReviewInstance.
stop	exec	access_review_schedule_definition_id, access_review_instance_id		Stop a currently active accessReviewInstance. After the access review instance stops, the instance status is marked as Completed, the reviewers can no longer give input, and the access review decisions are applied. Stopping an instance will not stop future instances. To prevent a recurring access review from starting future instances, update the schedule definition to change its scheduled end date.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
access_review_instance_id	string	The unique identifier of accessReviewInstance
access_review_schedule_definition_id	string	The unique identifier of accessReviewScheduleDefinition
If-Match	string	ETag

SELECT examples

get

Read the properties and relationships of an accessReviewInstance object.

SELECT
id,
contactedReviewers,
decisions,
endDateTime,
fallbackReviewers,
reviewers,
scope,
stages,
startDateTime,
status
FROM entra_id.identity_governance.access_reviews_definitions_instances
WHERE access_review_schedule_definition_id = '{{ access_review_schedule_definition_id }}' -- required
AND access_review_instance_id = '{{ access_review_instance_id }}' -- required
;

list

Get a list of the accessReviewInstance objects and their properties.

SELECT
id,
contactedReviewers,
decisions,
endDateTime,
fallbackReviewers,
reviewers,
scope,
stages,
startDateTime,
status
FROM entra_id.identity_governance.access_reviews_definitions_instances
WHERE access_review_schedule_definition_id = '{{ access_review_schedule_definition_id }}' -- required
;

INSERT examples

insert

No description available.

INSERT INTO entra_id.identity_governance.access_reviews_definitions_instances (
id,
endDateTime,
fallbackReviewers,
reviewers,
scope,
startDateTime,
status,
contactedReviewers,
decisions,
stages,
access_review_schedule_definition_id
)
SELECT 
'{{ id }}',
'{{ endDateTime }}',
'{{ fallbackReviewers }}',
'{{ reviewers }}',
'{{ scope }}',
'{{ startDateTime }}',
'{{ status }}',
'{{ contactedReviewers }}',
'{{ decisions }}',
'{{ stages }}',
'{{ access_review_schedule_definition_id }}'
RETURNING
id,
contactedReviewers,
decisions,
endDateTime,
fallbackReviewers,
reviewers,
scope,
stages,
startDateTime,
status
;

Manifest

# Description fields are for documentation purposes
- name: access_reviews_definitions_instances
props:
  - name: access_review_schedule_definition_id
    value: "{{ access_review_schedule_definition_id }}"
    description: Required parameter for the access_reviews_definitions_instances resource.
  - name: id
    value: "{{ id }}"
    description: |
      The unique identifier for an entity. Read-only.
  - name: endDateTime
    value: "{{ endDateTime }}"
    description: |
      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.
  - name: fallbackReviewers
    description: |
      This collection of reviewer scopes is used to define the list of fallback reviewers. These fallback reviewers will be 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 does not exist, or manager is specified as reviewer but a user's manager does not exist. Supports $select.
    value:
      - query: "{{ query }}"
        queryRoot: "{{ queryRoot }}"
        queryType: "{{ queryType }}"
  - name: reviewers
    description: |
      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.
    value:
      - query: "{{ query }}"
        queryRoot: "{{ queryRoot }}"
        queryType: "{{ queryType }}"
  - name: scope
    value: "{{ scope }}"
    description: |
      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.
  - name: startDateTime
    value: "{{ startDateTime }}"
    description: |
      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.
  - name: status
    value: "{{ status }}"
    description: |
      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.
  - name: contactedReviewers
    description: |
      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.
    value:
      - id: "{{ id }}"
        createdDateTime: "{{ createdDateTime }}"
        displayName: "{{ displayName }}"
        userPrincipalName: "{{ userPrincipalName }}"
  - name: decisions
    description: |
      Each user reviewed in an accessReviewInstance has a decision item representing if they were approved, denied, or not yet reviewed.
    value:
      - id: "{{ id }}"
        accessReviewId: "{{ accessReviewId }}"
        appliedBy: "{{ appliedBy }}"
        appliedDateTime: "{{ appliedDateTime }}"
        applyResult: "{{ applyResult }}"
        decision: "{{ decision }}"
        justification: "{{ justification }}"
        principal: "{{ principal }}"
        principalLink: "{{ principalLink }}"
        recommendation: "{{ recommendation }}"
        resource: "{{ resource }}"
        resourceLink: "{{ resourceLink }}"
        reviewedBy: "{{ reviewedBy }}"
        reviewedDateTime: "{{ reviewedDateTime }}"
        insights: "{{ insights }}"
  - name: stages
    description: |
      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.
    value:
      - id: "{{ id }}"
        endDateTime: "{{ endDateTime }}"
        fallbackReviewers: "{{ fallbackReviewers }}"
        reviewers: "{{ reviewers }}"
        startDateTime: "{{ startDateTime }}"
        status: "{{ status }}"
        decisions: "{{ decisions }}"

UPDATE examples

update

Update the properties of an accessReviewInstance object. Only the reviewers and fallbackReviewers properties can be updated but the scope property is also required in the request body. You can only add reviewers to the fallbackReviewers property but can't remove existing fallbackReviewers. To update an accessReviewInstance, it's status must be InProgress.

UPDATE entra_id.identity_governance.access_reviews_definitions_instances
SET 
id = '{{ id }}',
endDateTime = '{{ endDateTime }}',
fallbackReviewers = '{{ fallbackReviewers }}',
reviewers = '{{ reviewers }}',
scope = '{{ scope }}',
startDateTime = '{{ startDateTime }}',
status = '{{ status }}',
contactedReviewers = '{{ contactedReviewers }}',
decisions = '{{ decisions }}',
stages = '{{ stages }}'
WHERE 
access_review_schedule_definition_id = '{{ access_review_schedule_definition_id }}' --required
AND access_review_instance_id = '{{ access_review_instance_id }}' --required
RETURNING
id,
contactedReviewers,
decisions,
endDateTime,
fallbackReviewers,
reviewers,
scope,
stages,
startDateTime,
status;

DELETE examples

delete

No description available.

DELETE FROM entra_id.identity_governance.access_reviews_definitions_instances
WHERE access_review_schedule_definition_id = '{{ access_review_schedule_definition_id }}' --required
AND access_review_instance_id = '{{ access_review_instance_id }}' --required
AND If-Match = '{{ If-Match }}'
;

Lifecycle Methods

accept_recommendations

Allows the acceptance of recommendations on all accessReviewInstanceDecisionItem objects that haven't been reviewed on an accessReviewInstance object for which the calling user is a reviewer.

EXEC entra_id.identity_governance.access_reviews_definitions_instances.accept_recommendations 
@access_review_schedule_definition_id='{{ access_review_schedule_definition_id }}' --required, 
@access_review_instance_id='{{ access_review_instance_id }}' --required
;

apply_decisions

Apply review decisions on an accessReviewInstance if the decisions were not applied automatically because the autoApplyDecisionsEnabled property is false in the review's accessReviewScheduleSettings. The status of the accessReviewInstance must be Completed to call this method.

EXEC entra_id.identity_governance.access_reviews_definitions_instances.apply_decisions 
@access_review_schedule_definition_id='{{ access_review_schedule_definition_id }}' --required, 
@access_review_instance_id='{{ access_review_instance_id }}' --required
;

batch_record_decisions

Enables reviewers to review all accessReviewInstanceDecisionItem objects in batches by using principalId, resourceId, or neither.

EXEC entra_id.identity_governance.access_reviews_definitions_instances.batch_record_decisions 
@access_review_schedule_definition_id='{{ access_review_schedule_definition_id }}' --required, 
@access_review_instance_id='{{ access_review_instance_id }}' --required 
@@json=
'{
"decision": "{{ decision }}", 
"justification": "{{ justification }}", 
"principalId": "{{ principalId }}", 
"resourceId": "{{ resourceId }}"
}'
;

reset_decisions

Resets all accessReviewInstanceDecisionItem objects on an accessReviewInstance to notReviewed.

EXEC entra_id.identity_governance.access_reviews_definitions_instances.reset_decisions 
@access_review_schedule_definition_id='{{ access_review_schedule_definition_id }}' --required, 
@access_review_instance_id='{{ access_review_instance_id }}' --required
;

send_reminder

Send a reminder to the reviewers of an active accessReviewInstance.

EXEC entra_id.identity_governance.access_reviews_definitions_instances.send_reminder 
@access_review_schedule_definition_id='{{ access_review_schedule_definition_id }}' --required, 
@access_review_instance_id='{{ access_review_instance_id }}' --required
;

stop

Stop a currently active accessReviewInstance. After the access review instance stops, the instance status is marked as Completed, the reviewers can no longer give input, and the access review decisions are applied. Stopping an instance will not stop future instances. To prevent a recurring access review from starting future instances, update the schedule definition to change its scheduled end date.

EXEC entra_id.identity_governance.access_reviews_definitions_instances.stop 
@access_review_schedule_definition_id='{{ access_review_schedule_definition_id }}' --required, 
@access_review_instance_id='{{ access_review_instance_id }}' --required
;