M365 Blogs

How to Use Restore-MgDirectoryDeletedItem to Restore Directory Users?

Have you ever accidentally deleted a user in Microsoft Entra ID (Azure AD)? Don’t panic—Microsoft Graph PowerShell gives you the tools to recover the user quickly. In this article, you’ll learn how to use the Restore-MgDirectoryDeletedItem cmdlet to bring deleted directory users back to life.

What is Restore-MgDirectoryDeletedItem?

Restore-MgDirectoryDeletedItem is a Microsoft Graph PowerShell cmdlet that restores soft-deleted directory objects—most commonly users—within the retention period.

Microsoft Entra ID (Azure AD) retains deleted users for 30 days by default, giving admins a grace period to restore them if needed.

Why Use Restore-MgDirectoryDeletedItem?

Here’s why this cmdlet is so useful:

Accidental Deletions: Mistakenly removed a user? Restore them quickly.
Offboarding Reversals: Need to reinstate a user after a termination decision was reversed.
Testing/Training Scenarios: Restore test users after trying out deletion workflows.
Data Recovery: Prevent permanent loss of data associated with the users by restoring users in time.

It’s a critical command to have in your admin toolkit for ensuring business continuity.

Cmdlet Syntax

Restore-MgDirectoryDeletedItem -DirectoryObjectId <String>

Parameters:

-DirectoryObjectId – The object ID of the deleted user you want to restore. This ID is retrieved using the Get-MgDirectoryDeletedItemAsUser cmdlet.

Usage Examples

Listing Deleted Users

Before you can restore a user, you must get their deleted object ID.

Get-MgDirectoryDeletedItemAsUser

This returns a list of deleted users with details like Id, DisplayName, and UserPrincipalName. Copy the Id of the user you want to restore.

Restoring a Deleted User

Restore-MgDirectoryDeletedItem -DirectoryObjectId "c71e4a5f-e379-4389-8f6e-af9057860fa1"

This command restores the deleted user with the given object ID. Once restored, the user account reappears in the active directory and retains its previous properties.

Frequently Asked Questions

How long do I have to restore a deleted user?

You have 30 days from the deletion date. After that, the object is permanently deleted.

Can I restore other types of directory objects?

Yes! You can also restore groups and applications, not just users, if they were soft-deleted.

Do I need special permissions?

Yes. You must have Directory.AccessAsUser.All or User.ReadWrite.All Graph API permissions with appropriate admin consent.

Use Cases

Scenario	How It Helps
Accidental Deletion	Quickly recover mistakenly deleted users without recreating them from scratch.
Business Reinstatement	Bring users back into the system if offboarding decisions are reversed.
Disaster Recovery	Avoid data or license loss in high-stakes admin errors.
Test User Reuse	Restore training or development users for re-use without rebuilding.

⚠️ Not All Objects Can Be Restored

The Restore-MgDirectoryDeletedItem cmdlet can recover deleted users, groups, and certain directory objects, but some objects (like applications or service principals) cannot be restored. Always verify object types before attempting recovery to avoid confusion.

⏳ Retention Period Is Limited

Deleted directory objects are only available for restoration within 30 days (the soft-delete period). After this window, they are permanently deleted and cannot be recovered. Plan timely actions to restore critical accounts or groups before the retention expires.

Conclusion

The Restore-MgDirectoryDeletedItem cmdlet is a lifesaver for Microsoft 365 admins managing user identities. Whether it’s an accidental deletion or a quick reversal, this command lets you restore user accounts within seconds—along with their properties and configurations.

Make it part of your standard admin recovery toolkit, and combine it with Get-MgDirectoryDeletedItemAsUser to build a robust user restoration workflow.

Did You Know? Managing Microsoft 365 applications is even easier with automation. Try our Graph PowerShell scripts to automate tasks like generating reports, cleaning up inactive Teams, or assigning licenses efficiently.

Ready to get the most out of Microsoft 365 tools? Explore our free Microsoft 365 administration tools to simplify your administrative tasks and boost productivity.