deleted_items
Creates, updates, deletes, gets or lists a deleted_items resource.
Overview
| Name | deleted_items |
| Type | Resource |
| Id | entra_id.directory.deleted_items |
Fields
The following fields are returned by SELECT queries:
- get
- list
Retrieved navigation property
| Name | Datatype | Description |
|---|---|---|
id | string | The unique identifier for an entity. Read-only. |
deletedDateTime | string (date-time) | Date and time when this object was deleted. Always null when the object hasn't been deleted. (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])$) |
Retrieved collection
| Name | Datatype | Description |
|---|---|---|
id | string | The unique identifier for an entity. Read-only. |
deletedDateTime | string (date-time) | Date and time when this object was deleted. Always null when the object hasn't been deleted. (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])$) |
Methods
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
get | select | directory_object_id | Retrieve the properties of a recently deleted directory object from deleted items. The following types are supported: - administrativeUnit - application - agentIdentityBlueprint - agentIdentity - agentIdentityBlueprintPrincipal - agentUser - certificateBasedAuthPki - certificateAuthorityDetail - group - servicePrincipal - user | |
list | select | Retrieve the properties of a recently deleted directory object from deleted items. The following types are supported: - administrativeUnit - application - agentIdentityBlueprint - agentIdentity - agentIdentityBlueprintPrincipal - agentUser - certificateBasedAuthPki - certificateAuthorityDetail - group - servicePrincipal - user | ||
delete | delete | directory_object_id | If-Match | Permanently delete a recently deleted directory object from deleted items. The following types are supported: - application - agentIdentityBlueprint - agentIdentity - agentIdentityBlueprintPrincipal - agentUser - certificateBasedAuthPki - certificateAuthorityDetail - group - servicePrincipal - user After an item is permanently deleted, it cannot be restored. Administrative units cannot be permanently deleted by using the deletedItems API. Soft-deleted administrative units will be permanently deleted 30 days after initial deletion unless they are restored. |
get_available_extension_properties | exec | Return all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension properties: | ||
get_by_ids | exec | Return the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function are to: | ||
validate_properties | exec | Validate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display name or mail nickname is valid before trying to create a Microsoft 365 group. To validate the properties of an existing group, use the group: validateProperties function. The following policy validations are performed for the display name and mail nickname properties: 1. Validate the prefix and suffix naming policy 2. Validate the custom banned words policy 3. Validate that the mail nickname is unique This API only returns the first validation failure that is encountered. If the properties fail multiple validations, only the first validation failure is returned. However, you can validate both the mail nickname and the display name and receive a collection of validation errors if you're only validating the prefix and suffix naming policy. To learn more about configuring naming policies, see Configure naming policy. | ||
check_member_groups | exec | directory_object_id | Check for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object can be of one of the following types: - user - group - service principal - organizational contact - device - directory object This function is transitive. You can check up to a maximum of 20 groups per request. This function supports all groups provisioned in Microsoft Entra ID. Because Microsoft 365 groups cannot contain other groups, membership in a Microsoft 365 group is always direct. | |
check_member_objects | exec | directory_object_id | ||
get_member_groups | exec | directory_object_id | Return all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of. This function is transitive. This API returns up to 11,000 group IDs. If more than 11,000 results are available, it returns a 400 Bad Request error with the DirectoryResultSizeLimitExceeded error code. If you get the DirectoryResultSizeLimitExceeded error code, use the List group transitive memberOf API instead. | |
get_member_objects | exec | directory_object_id | Return all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of: - user - group - service principal - organizational contact - device - directory object This function is transitive. Only users and role-enabled groups can be members of directory roles. | |
restore | exec | directory_object_id | Restore a recently deleted directory object from deleted items. The following types are supported: - administrativeUnit - application - agentIdentityBlueprint - agentIdentity - agentIdentityBlueprintPrincipal - agentUser - certificateBasedAuthPki - certificateAuthorityDetail - group - servicePrincipal - user If an item is accidentally deleted, you can fully restore the item. Additionally, restoring an application doesn't automatically restore the associated service principal automatically. You must call this API to explicitly restore the deleted service principal. A recently deleted item remains available for up to 30 days. After 30 days, the item is permanently deleted. |
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 |
|---|---|---|
directory_object_id | string | The unique identifier of directoryObject |
If-Match | string | ETag |
SELECT examples
- get
- list
Retrieve the properties of a recently deleted directory object from deleted items. The following types are supported:
- administrativeUnit
- application
- agentIdentityBlueprint
- agentIdentity
- agentIdentityBlueprintPrincipal
- agentUser
- certificateBasedAuthPki
- certificateAuthorityDetail
- group
- servicePrincipal
- user
SELECT
id,
deletedDateTime
FROM entra_id.directory.deleted_items
WHERE directory_object_id = '{{ directory_object_id }}' -- required
;
Retrieve the properties of a recently deleted directory object from deleted items. The following types are supported:
- administrativeUnit
- application
- agentIdentityBlueprint
- agentIdentity
- agentIdentityBlueprintPrincipal
- agentUser
- certificateBasedAuthPki
- certificateAuthorityDetail
- group
- servicePrincipal
- user
SELECT
id,
deletedDateTime
FROM entra_id.directory.deleted_items
;
DELETE examples
- delete
Permanently delete a recently deleted directory object from deleted items. The following types are supported:
- application
- agentIdentityBlueprint
- agentIdentity
- agentIdentityBlueprintPrincipal
- agentUser
- certificateBasedAuthPki
- certificateAuthorityDetail
- group
- servicePrincipal
- user After an item is permanently deleted, it cannot be restored. Administrative units cannot be permanently deleted by using the deletedItems API. Soft-deleted administrative units will be permanently deleted 30 days after initial deletion unless they are restored.
DELETE FROM entra_id.directory.deleted_items
WHERE directory_object_id = '{{ directory_object_id }}' --required
AND If-Match = '{{ If-Match }}'
;
Lifecycle Methods
- get_available_extension_properties
- get_by_ids
- validate_properties
- check_member_groups
- check_member_objects
- get_member_groups
- get_member_objects
- restore
Return all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension properties:
EXEC entra_id.directory.deleted_items.get_available_extension_properties
@@json=
'{
"isSyncedFromOnPremises": {{ isSyncedFromOnPremises }}
}'
;
Return the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function are to:
EXEC entra_id.directory.deleted_items.get_by_ids
@@json=
'{
"ids": "{{ ids }}",
"types": "{{ types }}"
}'
;
Validate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display name or mail nickname is valid before trying to create a Microsoft 365 group. To validate the properties of an existing group, use the group: validateProperties function. The following policy validations are performed for the display name and mail nickname properties:
1. Validate the prefix and suffix naming policy
2. Validate the custom banned words policy
3. Validate that the mail nickname is unique This API only returns the first validation failure that is encountered. If the properties fail multiple validations, only the first validation failure is returned. However, you can validate both the mail nickname and the display name and receive a collection of validation errors if you're only validating the prefix and suffix naming policy. To learn more about configuring naming policies, see Configure naming policy.
EXEC entra_id.directory.deleted_items.validate_properties
@@json=
'{
"entityType": "{{ entityType }}",
"displayName": "{{ displayName }}",
"mailNickname": "{{ mailNickname }}",
"onBehalfOfUserId": "{{ onBehalfOfUserId }}"
}'
;
Check for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object can be of one of the following types:
- user
- group
- service principal
- organizational contact
- device
- directory object This function is transitive. You can check up to a maximum of 20 groups per request. This function supports all groups provisioned in Microsoft Entra ID. Because Microsoft 365 groups cannot contain other groups, membership in a Microsoft 365 group is always direct.
EXEC entra_id.directory.deleted_items.check_member_groups
@directory_object_id='{{ directory_object_id }}' --required
@@json=
'{
"groupIds": "{{ groupIds }}"
}'
;
Success
EXEC entra_id.directory.deleted_items.check_member_objects
@directory_object_id='{{ directory_object_id }}' --required
@@json=
'{
"ids": "{{ ids }}"
}'
;
Return all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of. This function is transitive. This API returns up to 11,000 group IDs. If more than 11,000 results are available, it returns a 400 Bad Request error with the DirectoryResultSizeLimitExceeded error code. If you get the DirectoryResultSizeLimitExceeded error code, use the List group transitive memberOf API instead.
EXEC entra_id.directory.deleted_items.get_member_groups
@directory_object_id='{{ directory_object_id }}' --required
@@json=
'{
"securityEnabledOnly": {{ securityEnabledOnly }}
}'
;
Return all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of:
- user
- group
- service principal
- organizational contact
- device
- directory object This function is transitive. Only users and role-enabled groups can be members of directory roles.
EXEC entra_id.directory.deleted_items.get_member_objects
@directory_object_id='{{ directory_object_id }}' --required
@@json=
'{
"securityEnabledOnly": {{ securityEnabledOnly }}
}'
;
Restore a recently deleted directory object from deleted items. The following types are supported:
- administrativeUnit
- application
- agentIdentityBlueprint
- agentIdentity
- agentIdentityBlueprintPrincipal
- agentUser
- certificateBasedAuthPki
- certificateAuthorityDetail
- group
- servicePrincipal
- user If an item is accidentally deleted, you can fully restore the item. Additionally, restoring an application doesn't automatically restore the associated service principal automatically. You must call this API to explicitly restore the deleted service principal. A recently deleted item remains available for up to 30 days. After 30 days, the item is permanently deleted.
EXEC entra_id.directory.deleted_items.restore
@directory_object_id='{{ directory_object_id }}' --required
;