Permanently delete item (directory object)

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.

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

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.

Important

Hard deletion protection blocks permanent deletion of a protected user (excluding on-premises synchronized users), cloud-only group, application, or servicePrincipal for the first seven days after soft deletion. Protection is enabled by setting isHardDeleteProtectionEnabled to true on an existing object and can't be disabled.

The object can still be soft deleted and restored. If a protected object is restored and then soft deleted again, a new seven-day protection period begins. After the protection period expires, an authorized caller can permanently delete the object.

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
application	Application.ReadWrite.All	Not supported.	Application.ReadWrite.OwnedBy
agentIdentity	AgentIdentity.ReadWrite.All	Not supported.	AgentIdentity.ReadWrite.All
agentIdentityBlueprint	AgentIdentityBlueprint.ReadWrite.All	Not supported.	AgentIdentityBlueprint.ReadWrite.All
agentIdentityBlueprintPrincipal	AgentIdentityBlueprintPrincipal.ReadWrite.All	Not supported.	AgentIdentityBlueprintPrincipal.ReadWrite.All
agentUser	AgentIdUser.ReadWrite.IdentityParentedBy	Not supported.	AgentIdUser.ReadWrite.IdentityParentedBy
externalUserProfile	ExternalUserProfile.ReadWrite.All	Not supported	ExternalUserProfile.ReadWrite.All
certificateBasedAuthPki	PublicKeyInfrastructure.Read.All	Not supported.	PublicKeyInfrastructure.Read.All
certificateAuthorityDetail	PublicKeyInfrastructure.Read.All	Not supported.	PublicKeyInfrastructure.Read.All
device	Device.ReadWrite.All	Not supported.	Device.ReadWrite.All
group	Group.ReadWrite.All	Not supported.	Not supported.
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

For delegated access using work or school accounts, the signed-in user must be assigned a supported Microsoft Entra role or a custom role that grants the permissions required for this operation. This operation supports the following built-in roles, which provide only the least privilege necessary:

Agent identities, agent identity blueprints, and agent identity blueprint principals: Agent ID Administrator
Administrative units: Directory Readers (read-only), Global Readers (read-only), Privileged Role Administrator
Applications: Hybrid Identity Administrator, Cloud Application Administrator, Application Administrator
Devices: Cloud Device Administrator, Intune Administrator, Windows 365 Administrator
External user profiles: Global Reader (read-only), Skype for Business Administrator, Teams Administrator
Groups: Groups Administrator (except for role-assignable groups), User Administrator (except for role-assignable groups), Privileged Role Administrator (least privileged role for role-assignable groups)
Pending external user profiles: Global Reader (read-only), Skype for Business Administrator, Teams Administrator
Service principals: Hybrid Identity Administrator, Cloud Application Administrator, Application Administrator
Users: Authentication Administrator, Privileged Authentication Administrator, 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?.

HTTP request

DELETE /directory/deletedItems/{id}

Request headers

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

Request body

Don't supply a request body for this method.

Response

If successful, this method returns 204 No Content response code. It doesn't return anything in the response body.

If hard deletion protection is enabled and the object is still within the seven-day protection period, this method returns 409 Conflict with the Request_ConflictingRequest error code. Wait until the protection period expires before trying to permanently delete the object.

Examples

Example 1: Permanently delete an item

Request

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


// 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
await graphClient.Directory.DeletedItems["{directoryObject-id}"].DeleteAsync();

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.



// 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
graphClient.Directory().DeletedItems().ByDirectoryObjectId("directoryObject-id").Delete(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);

graphClient.directory().deletedItems().byDirectoryObjectId("{directoryObject-id}").delete();

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')
	.version('beta')
	.delete();

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);


$graphServiceClient->directory()->deletedItems()->byDirectoryObjectId('directoryObject-id')->delete()->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

Remove-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

await graph_client.directory.deleted_items.by_directory_object_id('directoryObject-id').delete()

Important

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

Response

HTTP/1.1 204 No Content

Example 2: Attempt to permanently delete a protected item

Request

The following request attempts to permanently delete an object with isHardDeleteProtectionEnabled set to true before its seven-day protection period expires.

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

Response

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "Request_ConflictingRequest",
    "message": "The object cannot be permanently deleted because isHardDeleteProtectionEnabled is set to true.",
    "innerError": {
      "date": "2026-10-30T12:00:00",
      "request-id": "a9ee5607-56bd-4ce1-bcf5-66a11c8358b0",
      "client-request-id": "7fc3fe7b-2070-4f3f-8b0c-949ae8c03509"
    }
  }
}

Feedback

Was this page helpful?

Last updated on 2026-11-07

Permanently delete item (directory object)

Permissions

HTTP request

Request headers

Request body

Response

Examples

Example 1: Permanently delete an item

Request

Response

Example 2: Attempt to permanently delete a protected item

Request

Response

Feedback

Additional resources