Restore deleted item (directory object)

Article
2024-12-25

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.

Restore a recently deleted directory object from deleted items. The following types are supported:

If an item was accidentally deleted, you can fully restore the item. This isn't applicable to security groups, which are deleted permanently. Also, restoring an application doesn't 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.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

The following table shows the least privileged permission or permissions required to call this API on each supported resource type. Follow best practices to request least privileged permissions. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Supported resource	Delegated (work or school account)	Delegated (personal Microsoft account)	Application
administrativeUnit	AdministrativeUnit.ReadWrite.All	Not supported.	AdministrativeUnit.ReadWrite.All
application	Application.ReadWrite.All	Not supported.	Application.ReadWrite.OwnedBy
certificateBasedAuthPki	PublicKeyInfrastructure.Read.All	Not supported.	PublicKeyInfrastructure.Read.All
certificateAuthorityDetail	PublicKeyInfrastructure.Read.All	Not supported.	PublicKeyInfrastructure.Read.All
externalUserProfile	ExternalUserProfile.ReadWrite.All	Not supported	ExternalUserProfile.ReadWrite.All
group	Group.ReadWrite.All	Not supported.	Group.ReadWrite.All
pendingExternalUserProfile	PendingExternalUserProfile.ReadWrite.All	Not supported	PendingExternalUserProfile.ReadWrite.All
servicePrincipal	Application.ReadWrite.All	Not supported.	Application.ReadWrite.OwnedBy
user	User.DeleteRestore.All	Not supported.	User.DeleteRestore.All

Important

In delegated scenarios with work or school accounts, the signed-in user must be assigned a supported Microsoft Entra role or a custom role with a supported role permission. The following least privileged roles are supported for this operation.

To restore deleted applications or service principals: Application Administrator, Cloud Application Administrator, or Hybrid Identity Administrator.
To restore deleted users: User Administrator. However, to restore users with privileged administrator roles:
- In delegated scenarios, the app must be assigned the Directory.AccessAsUser.All delegated permission, and the calling user must also be assigned a higher privileged administrator role as indicated in Who can perform sensitive actions?.
- In app-only scenarios and in addition to being granted the User.ReadWrite.All application permission, the app must be assigned a higher privileged administrator role as indicated in Who can perform sensitive actions?.
To restore deleted groups: Groups Administrator. However, to restore role-assignable groups, the calling user must be assigned the Privileged Role Administrator role.

HTTP request

POST /directory/deleteditems/{id}/restore

Request headers

Name	Description
Authorization	Bearer {token}. Required. Learn more about authentication and authorization.
Content-type	application/json

Request body

In the request body, supply a JSON representation of the parameters.

The following table lists the parameters that are required when you call this action.

Parameter	Type	Description
autoReconcileProxyConflict	Boolean	Optional parameter. Indicates whether Microsoft Entra ID should remove any conflicting proxy addresses while restoring a soft-deleted user whose one or more proxy addresses are currently used for an active user. Used only for restoring soft-deleted user. The default value for this paramater is `false`.
newUserPrincipalName	String	The new userPrincipalName to add to the restored user. Optional.

Response

If successful, this method returns a 200 OK response code and a directoryObject object in the response body.

Examples

Example 1: Restore a deleted directory object

Request

POST https://graph.microsoft.com/beta/directory/deleteditems/46cc6179-19d0-473e-97ad-6ff84347bbbb/restore


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Directory.DeletedItems["{directoryObject-id}"].Restore.PostAsync();

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta directory deleted-items restore post --directory-object-id {directoryObject-id}

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
restore, err := graphClient.Directory().DeletedItems().ByDirectoryObjectId("directoryObject-id").Restore().Post(context.Background(), nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.directory().deletedItems().byDirectoryObjectId("{directoryObject-id}").restore().post();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

await client.api('/directory/deleteditems/46cc6179-19d0-473e-97ad-6ff84347bbbb/restore')
	.version('beta')
	.post();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->directory()->deletedItems()->byDirectoryObjectId('directoryObject-id')->restore()->post()->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement

Restore-MgBetaDirectoryDeletedItem -DirectoryObjectId $directoryObjectId

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.directory.deleted_items.by_directory_object_id('directoryObject-id').restore.post()

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects/$entity",
  "@odata.type":"#microsoft.graph.group",
  "id":"46cc6179-19d0-473e-97ad-6ff84347bbbb",
  "displayName":"SampleGroup",
  "groupTypes":["Unified"],
  "mail":"[email protected]",
  "mailEnabled":true,
  "mailNickname":"Example",
  "securityEnabled":false,
  "visibility":"Public"
}

Example 2: Restore a deleted user and remove conflicting proxy addresses

Request

POST https://graph.microsoft.com/beta/directory/deleteditems/78bf875b-9343-4edc-9130-0d3958113563/restore
Content-Type: application/json

{
  "autoReconcileProxyConflict": true
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.DirectoryNamespace.DeletedItems.Item.Restore;

var requestBody = new RestorePostRequestBody
{
	AdditionalData = new Dictionary<string, object>
	{
		{
			"autoReconcileProxyConflict" , true
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Directory.DeletedItems["{directoryObject-id}"].Restore.PostAsync(requestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta directory deleted-items restore post --directory-object-id {directoryObject-id} --body '{\
  "autoReconcileProxyConflict": true\
}\
'

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphdirectory "github.com/microsoftgraph/msgraph-beta-sdk-go/directory"
	  //other-imports
)

requestBody := graphdirectory.NewRestorePostRequestBody()
additionalData := map[string]interface{}{
	autoReconcileProxyConflict := true
requestBody.SetAutoReconcileProxyConflict(&autoReconcileProxyConflict) 
}
requestBody.SetAdditionalData(additionalData)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
restore, err := graphClient.Directory().DeletedItems().ByDirectoryObjectId("directoryObject-id").Restore().Post(context.Background(), requestBody, nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.beta.directory.deleteditems.item.restore.RestorePostRequestBody restorePostRequestBody = new com.microsoft.graph.beta.directory.deleteditems.item.restore.RestorePostRequestBody();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("autoReconcileProxyConflict", true);
restorePostRequestBody.setAdditionalData(additionalData);
var result = graphClient.directory().deletedItems().byDirectoryObjectId("{directoryObject-id}").restore().post(restorePostRequestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const directoryObject = {
  autoReconcileProxyConflict: true
};

await client.api('/directory/deleteditems/78bf875b-9343-4edc-9130-0d3958113563/restore')
	.version('beta')
	.post(directoryObject);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Directory\DeletedItems\Item\Restore\RestorePostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new RestorePostRequestBody();
$additionalData = [
	'autoReconcileProxyConflict' => true,
];
$requestBody->setAdditionalData($additionalData);

$result = $graphServiceClient->directory()->deletedItems()->byDirectoryObjectId('directoryObject-id')->restore()->post($requestBody)->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement

$params = @{
	autoReconcileProxyConflict = $true
}

Restore-MgBetaDirectoryDeletedItem -DirectoryObjectId $directoryObjectId -BodyParameter $params

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.directory.deleteditems.item.restore.restore_post_request_body import RestorePostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = RestorePostRequestBody(
	additional_data = {
			"auto_reconcile_proxy_conflict" : True,
	}
)

result = await graph_client.directory.deleted_items.by_directory_object_id('directoryObject-id').restore.post(request_body)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users/$entity",
    "@odata.type": "#microsoft.graph.user",
    "id": "78bf875b-9343-4edc-9130-0d3958113563",
    "businessPhones": [],
    "displayName": "SampleUser",
    "givenName": "Sample",
    "jobTitle": "Product Marketing Manager",
    "mail": "[email protected]",
    "mobilePhone": "+1 425 555 0109",
    "officeLocation": "18/2111",
    "preferredLanguage": "en-US",
    "surname": "Vance",
    "userPrincipalName": "[email protected]"
}

Example 3: Restore a deleted user and assign them a new userPrincipalName

Request

POST https://graph.microsoft.com/beta/directory/deleteditems/78bf875b-9343-4edc-9130-0d3958113563/restore
Content-Type: application/json

{
  "newUserPrincipalName": "[email protected]"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.DirectoryNamespace.DeletedItems.Item.Restore;

var requestBody = new RestorePostRequestBody
{
	AdditionalData = new Dictionary<string, object>
	{
		{
			"newUserPrincipalName" , "[email protected]"
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Directory.DeletedItems["{directoryObject-id}"].Restore.PostAsync(requestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta directory deleted-items restore post --directory-object-id {directoryObject-id} --body '{\
  "newUserPrincipalName": "[email protected]"\
}\
'

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphdirectory "github.com/microsoftgraph/msgraph-beta-sdk-go/directory"
	  //other-imports
)

requestBody := graphdirectory.NewRestorePostRequestBody()
additionalData := map[string]interface{}{
	"newUserPrincipalName" : "[email protected]", 
}
requestBody.SetAdditionalData(additionalData)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
restore, err := graphClient.Directory().DeletedItems().ByDirectoryObjectId("directoryObject-id").Restore().Post(context.Background(), requestBody, nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.beta.directory.deleteditems.item.restore.RestorePostRequestBody restorePostRequestBody = new com.microsoft.graph.beta.directory.deleteditems.item.restore.RestorePostRequestBody();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("newUserPrincipalName", "[email protected]");
restorePostRequestBody.setAdditionalData(additionalData);
var result = graphClient.directory().deletedItems().byDirectoryObjectId("{directoryObject-id}").restore().post(restorePostRequestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const directoryObject = {
  newUserPrincipalName: '[email protected]'
};

await client.api('/directory/deleteditems/78bf875b-9343-4edc-9130-0d3958113563/restore')
	.version('beta')
	.post(directoryObject);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Directory\DeletedItems\Item\Restore\RestorePostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new RestorePostRequestBody();
$additionalData = [
	'newUserPrincipalName' => '[email protected]',
];
$requestBody->setAdditionalData($additionalData);

$result = $graphServiceClient->directory()->deletedItems()->byDirectoryObjectId('directoryObject-id')->restore()->post($requestBody)->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement

$params = @{
	newUserPrincipalName = "[email protected]"
}

Restore-MgBetaDirectoryDeletedItem -DirectoryObjectId $directoryObjectId -BodyParameter $params

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.directory.deleteditems.item.restore.restore_post_request_body import RestorePostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = RestorePostRequestBody(
	additional_data = {
			"new_user_principal_name" : "[email protected]",
	}
)

result = await graph_client.directory.deleted_items.by_directory_object_id('directoryObject-id').restore.post(request_body)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects/$entity",
    "@odata.type": "#microsoft.graph.user",
    "id": "78bf875b-9343-4edc-9130-0d3958113563",
    "businessPhones": [],
    "displayName": "SampleUser",
    "givenName": "Sample",
    "mobilePhone": "+1 425 555 0109",
    "officeLocation": "18/2111",
    "preferredLanguage": "en-US",
    "surname": "Vance",
    "userPrincipalName": "[email protected]"
}

Share via

Restore deleted item (directory object)

Permissions

HTTP request

Request headers

Request body

Response

Examples

Example 1: Restore a deleted directory object

Request

Response

Example 2: Restore a deleted user and remove conflicting proxy addresses

Request

Response

Example 3: Restore a deleted user and assign them a new userPrincipalName

Request

Response

Feedback

Additional resources