access_reviews_definitions

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

Overview

Name	access_reviews_definitions
Type	Resource
Id	entra_id.identity_governance.access_reviews_definitions

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.
additionalNotificationRecipients	array	Defines the list of additional users or group members to be notified of the access review progress.
createdBy		User who created this review. Read-only.
createdDateTime	string (date-time)	Timestamp when the access review series was created. 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])$)
descriptionForAdmins	string	Description provided by review creators to provide more context of the review to admins. Supports $select.
descriptionForReviewers	string	Description provided by review creators to provide more context of the review to reviewers. Reviewers see this description in the email sent to them requesting their review. Email notifications support up to 256 characters. Supports $select.
displayName	string	Name of the access review series. Supports $select and $orderby. Required on create.
fallbackReviewers	array	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. See accessReviewReviewerScope. Replaces backupReviewers. Supports $select. NOTE: The value of this property will be ignored if fallback reviewers are assigned through the stageSettings property.
instanceEnumerationScope		This property is required when scoping a review to guest users' access across all Microsoft 365 groups and determines which Microsoft 365 groups are reviewed. Each group becomes a unique accessReviewInstance of the access review series. For supported scopes, see accessReviewScope. Supports $select. For examples of options for configuring instanceEnumerationScope, see Configure the scope of your access review definition using the Microsoft Graph API.
instances	array	If the 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 resource under review in the accessReviewScheduleDefinition. If a review has multiple resources and multiple instances, each resource has a unique instance for each recurrence.
lastModifiedDateTime	string (date-time)	Timestamp when the access review series was last modified. 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])$)
reviewers	array	This collection of access review scopes is used to define who are the reviewers. The reviewers property is only updatable if individual users are assigned as reviewers. Required on create. Supports $select. For examples of options for assigning reviewers, see Assign reviewers to your access review definition using the Microsoft Graph API. NOTE: The value of this property will be ignored if reviewers are assigned through the stageSettings property.
scope		Defines the entities whose access is reviewed. For supported scopes, see accessReviewScope. Required on create. Supports $select and $filter (contains only). For examples of options for configuring scope, see Configure the scope of your access review definition using the Microsoft Graph API.
settings		The settings for an access review series, see type definition below. Supports $select. Required on create.
stageSettings	array	Required only for a multi-stage access review to define the stages and their settings. You can break down each review instance into up to three sequential stages, where each stage can have a different set of reviewers, fallback reviewers, and settings. Stages are created sequentially based on the dependsOn property. Optional. When this property is defined, its settings are used instead of the corresponding settings in the accessReviewScheduleDefinition object and its settings, reviewers, and fallbackReviewers properties.
status	string	This read-only field specifies the status of an access review. The typical states include 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.
additionalNotificationRecipients	array	Defines the list of additional users or group members to be notified of the access review progress.
createdBy		User who created this review. Read-only.
createdDateTime	string (date-time)	Timestamp when the access review series was created. 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])$)
descriptionForAdmins	string	Description provided by review creators to provide more context of the review to admins. Supports $select.
descriptionForReviewers	string	Description provided by review creators to provide more context of the review to reviewers. Reviewers see this description in the email sent to them requesting their review. Email notifications support up to 256 characters. Supports $select.
displayName	string	Name of the access review series. Supports $select and $orderby. Required on create.
fallbackReviewers	array	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. See accessReviewReviewerScope. Replaces backupReviewers. Supports $select. NOTE: The value of this property will be ignored if fallback reviewers are assigned through the stageSettings property.
instanceEnumerationScope		This property is required when scoping a review to guest users' access across all Microsoft 365 groups and determines which Microsoft 365 groups are reviewed. Each group becomes a unique accessReviewInstance of the access review series. For supported scopes, see accessReviewScope. Supports $select. For examples of options for configuring instanceEnumerationScope, see Configure the scope of your access review definition using the Microsoft Graph API.
instances	array	If the 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 resource under review in the accessReviewScheduleDefinition. If a review has multiple resources and multiple instances, each resource has a unique instance for each recurrence.
lastModifiedDateTime	string (date-time)	Timestamp when the access review series was last modified. 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])$)
reviewers	array	This collection of access review scopes is used to define who are the reviewers. The reviewers property is only updatable if individual users are assigned as reviewers. Required on create. Supports $select. For examples of options for assigning reviewers, see Assign reviewers to your access review definition using the Microsoft Graph API. NOTE: The value of this property will be ignored if reviewers are assigned through the stageSettings property.
scope		Defines the entities whose access is reviewed. For supported scopes, see accessReviewScope. Required on create. Supports $select and $filter (contains only). For examples of options for configuring scope, see Configure the scope of your access review definition using the Microsoft Graph API.
settings		The settings for an access review series, see type definition below. Supports $select. Required on create.
stageSettings	array	Required only for a multi-stage access review to define the stages and their settings. You can break down each review instance into up to three sequential stages, where each stage can have a different set of reviewers, fallback reviewers, and settings. Stages are created sequentially based on the dependsOn property. Optional. When this property is defined, its settings are used instead of the corresponding settings in the accessReviewScheduleDefinition object and its settings, reviewers, and fallbackReviewers properties.
status	string	This read-only field specifies the status of an access review. The typical states include 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		Read the properties and relationships of an accessReviewScheduleDefinition object. To retrieve the instances of the access review series, use the list accessReviewInstance API.
list	select			Get a list of the accessReviewScheduleDefinition objects and their properties.
insert	insert			Create a new accessReviewScheduleDefinition object.
replace	replace	access_review_schedule_definition_id		Update an existing accessReviewScheduleDefinition object to change one or more of its properties.
delete	delete	access_review_schedule_definition_id	If-Match	Deletes an accessReviewScheduleDefinition object.
stop	exec	access_review_schedule_definition_id

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_schedule_definition_id	string	The unique identifier of accessReviewScheduleDefinition
If-Match	string	ETag

SELECT examples

get

Read the properties and relationships of an accessReviewScheduleDefinition object. To retrieve the instances of the access review series, use the list accessReviewInstance API.

SELECT
id,
additionalNotificationRecipients,
createdBy,
createdDateTime,
descriptionForAdmins,
descriptionForReviewers,
displayName,
fallbackReviewers,
instanceEnumerationScope,
instances,
lastModifiedDateTime,
reviewers,
scope,
settings,
stageSettings,
status
FROM entra_id.identity_governance.access_reviews_definitions
WHERE access_review_schedule_definition_id = '{{ access_review_schedule_definition_id }}' -- required
;

list

Get a list of the accessReviewScheduleDefinition objects and their properties.

SELECT
id,
additionalNotificationRecipients,
createdBy,
createdDateTime,
descriptionForAdmins,
descriptionForReviewers,
displayName,
fallbackReviewers,
instanceEnumerationScope,
instances,
lastModifiedDateTime,
reviewers,
scope,
settings,
stageSettings,
status
FROM entra_id.identity_governance.access_reviews_definitions
;

INSERT examples

insert

Create a new accessReviewScheduleDefinition object.

INSERT INTO entra_id.identity_governance.access_reviews_definitions (
id,
additionalNotificationRecipients,
createdBy,
createdDateTime,
descriptionForAdmins,
descriptionForReviewers,
displayName,
fallbackReviewers,
instanceEnumerationScope,
lastModifiedDateTime,
reviewers,
scope,
settings,
stageSettings,
status,
instances
)
SELECT 
'{{ id }}',
'{{ additionalNotificationRecipients }}',
'{{ createdBy }}',
'{{ createdDateTime }}',
'{{ descriptionForAdmins }}',
'{{ descriptionForReviewers }}',
'{{ displayName }}',
'{{ fallbackReviewers }}',
'{{ instanceEnumerationScope }}',
'{{ lastModifiedDateTime }}',
'{{ reviewers }}',
'{{ scope }}',
'{{ settings }}',
'{{ stageSettings }}',
'{{ status }}',
'{{ instances }}'
RETURNING
id,
additionalNotificationRecipients,
createdBy,
createdDateTime,
descriptionForAdmins,
descriptionForReviewers,
displayName,
fallbackReviewers,
instanceEnumerationScope,
instances,
lastModifiedDateTime,
reviewers,
scope,
settings,
stageSettings,
status
;

Manifest

# Description fields are for documentation purposes
- name: access_reviews_definitions
props:
  - name: id
    value: "{{ id }}"
    description: |
      The unique identifier for an entity. Read-only.
  - name: additionalNotificationRecipients
    description: |
      Defines the list of additional users or group members to be notified of the access review progress.
    value:
      - notificationRecipientScope:
        notificationTemplateType: "{{ notificationTemplateType }}"
  - name: createdBy
    value: "{{ createdBy }}"
    description: |
      User who created this review. Read-only.
  - name: createdDateTime
    value: "{{ createdDateTime }}"
    description: |
      Timestamp when the access review series was created. Supports $select. Read-only.
  - name: descriptionForAdmins
    value: "{{ descriptionForAdmins }}"
    description: |
      Description provided by review creators to provide more context of the review to admins. Supports $select.
  - name: descriptionForReviewers
    value: "{{ descriptionForReviewers }}"
    description: |
      Description provided  by review creators to provide more context of the review to reviewers. Reviewers see this description in the email sent to them requesting their review. Email notifications support up to 256 characters. Supports $select.
  - name: displayName
    value: "{{ displayName }}"
    description: |
      Name of the access review series. Supports $select and $orderby. Required on create.
  - name: fallbackReviewers
    description: |
      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. See accessReviewReviewerScope. Replaces backupReviewers. Supports $select. NOTE: The value of this property will be ignored if fallback reviewers are assigned through the stageSettings property.
    value:
      - query: "{{ query }}"
        queryRoot: "{{ queryRoot }}"
        queryType: "{{ queryType }}"
  - name: instanceEnumerationScope
    value: "{{ instanceEnumerationScope }}"
    description: |
      This property is required when scoping a review to guest users' access across all Microsoft 365 groups and determines which Microsoft 365 groups are reviewed. Each group becomes a unique accessReviewInstance of the access review series.  For supported scopes, see accessReviewScope. Supports $select. For examples of options for configuring instanceEnumerationScope, see Configure the scope of your access review definition using the Microsoft Graph API.
  - name: lastModifiedDateTime
    value: "{{ lastModifiedDateTime }}"
    description: |
      Timestamp when the access review series was last modified. Supports $select. Read-only.
  - name: reviewers
    description: |
      This collection of access review scopes is used to define who are the reviewers. The reviewers property is only updatable if individual users are assigned as reviewers. Required on create. Supports $select. For examples of options for assigning reviewers, see Assign reviewers to your access review definition using the Microsoft Graph API. NOTE: The value of this property will be ignored if reviewers are assigned through the stageSettings property.
    value:
      - query: "{{ query }}"
        queryRoot: "{{ queryRoot }}"
        queryType: "{{ queryType }}"
  - name: scope
    value: "{{ scope }}"
    description: |
      Defines the entities whose access is reviewed. For supported scopes, see accessReviewScope. Required on create. Supports $select and $filter (contains only). For examples of options for configuring scope, see Configure the scope of your access review definition using the Microsoft Graph API.
  - name: settings
    value: "{{ settings }}"
    description: |
      The settings for an access review series, see type definition below. Supports $select. Required on create.
  - name: stageSettings
    description: |
      Required only for a multi-stage access review to define the stages and their settings. You can break down each review instance into up to three sequential stages, where each stage can have a different set of reviewers, fallback reviewers, and settings. Stages are created sequentially based on the dependsOn property. Optional.  When this property is defined, its settings are used instead of the corresponding settings in the accessReviewScheduleDefinition object and its settings, reviewers, and fallbackReviewers properties.
    value:
      - decisionsThatWillMoveToNextStage: "{{ decisionsThatWillMoveToNextStage }}"
        dependsOn: "{{ dependsOn }}"
        durationInDays: {{ durationInDays }}
        fallbackReviewers: "{{ fallbackReviewers }}"
        recommendationInsightSettings: "{{ recommendationInsightSettings }}"
        recommendationsEnabled: {{ recommendationsEnabled }}
        reviewers: "{{ reviewers }}"
        stageId: "{{ stageId }}"
  - name: status
    value: "{{ status }}"
    description: |
      This read-only field specifies the status of an access review. The typical states include Initializing, NotStarted, Starting, InProgress, Completing, Completed, AutoReviewing, and AutoReviewed.  Supports $select, $orderby, and $filter (eq only). Read-only.
  - name: instances
    description: |
      If the 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 resource under review in the accessReviewScheduleDefinition. If a review has multiple resources and multiple instances, each resource has a unique instance for each recurrence.
    value:
      - id: "{{ id }}"
        endDateTime: "{{ endDateTime }}"
        fallbackReviewers: "{{ fallbackReviewers }}"
        reviewers: "{{ reviewers }}"
        scope: "{{ scope }}"
        startDateTime: "{{ startDateTime }}"
        status: "{{ status }}"
        contactedReviewers: "{{ contactedReviewers }}"
        decisions: "{{ decisions }}"
        stages: "{{ stages }}"

REPLACE examples

replace

Update an existing accessReviewScheduleDefinition object to change one or more of its properties.

REPLACE entra_id.identity_governance.access_reviews_definitions
SET 
id = '{{ id }}',
additionalNotificationRecipients = '{{ additionalNotificationRecipients }}',
createdBy = '{{ createdBy }}',
createdDateTime = '{{ createdDateTime }}',
descriptionForAdmins = '{{ descriptionForAdmins }}',
descriptionForReviewers = '{{ descriptionForReviewers }}',
displayName = '{{ displayName }}',
fallbackReviewers = '{{ fallbackReviewers }}',
instanceEnumerationScope = '{{ instanceEnumerationScope }}',
lastModifiedDateTime = '{{ lastModifiedDateTime }}',
reviewers = '{{ reviewers }}',
scope = '{{ scope }}',
settings = '{{ settings }}',
stageSettings = '{{ stageSettings }}',
status = '{{ status }}',
instances = '{{ instances }}'
WHERE 
access_review_schedule_definition_id = '{{ access_review_schedule_definition_id }}' --required
RETURNING
id,
additionalNotificationRecipients,
createdBy,
createdDateTime,
descriptionForAdmins,
descriptionForReviewers,
displayName,
fallbackReviewers,
instanceEnumerationScope,
instances,
lastModifiedDateTime,
reviewers,
scope,
settings,
stageSettings,
status;

DELETE examples

delete

Deletes an accessReviewScheduleDefinition object.

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

Lifecycle Methods

stop

Success

EXEC entra_id.identity_governance.access_reviews_definitions.stop 
@access_review_schedule_definition_id='{{ access_review_schedule_definition_id }}' --required
;