Reference Topic

Deleting Work Items (Asynchronous Bulk Deletion)

The delete work items API method enables you to delete one or more work items asynchronously in a single request.

Prerequisites

Before making a "delete work items'' request, you must have an access token to sign the request. You can retrieve an access token using one of the following flows:

• Getting an access token using the Resource Owner flow
• Getting an access token using the Implicit flow

Additionally, you must have the following permissions:

• Be a service principal, or
• Be a Site Administrator.

Overview

The delete work items API method is a command method. It supports asynchronous deletion of up to 100 work items per request. Deletion is handled in the background using a task queue.

This method is useful when you need to manage or clean up large volumes of work items efficiently.

If any work item fails to delete, the system continues processing the remaining items and logs a warning. A callback URL is notified when the deletion task completes.

Authentication

See Authentication for more information about authenticating requests to the Advance API.

API Documentation

Request

Request URL

POST https://{tenancymoniker}.{domain}/HdaApi/rest/v2.0/WorkItems/Delete

Headers

Key	Required	Description	Example value
Authorization	Yes	The Authorization header for the request. Uses the access token retrieved (see Prerequisites section above for more information).	Bearer [access token]

Parameters

Name	Type	Location	Required	Description
tenancymoniker	String	URL	Yes	The tenancy moniker for the tenancy in which you want to create the new work item.
domain	String	URL	Yes	Your domain. For example, yourorganization.com
workItemIds	Guid	Body	Yes	A list of up to 100 work items to delete.
callbackUrl	String	Body	Yes	The URL to which a notification is sent when deletion completes.
callbackSecret	String	Body	No	Optional secret used to authenticate the callback request.

Examples

Example Request URL

https://yourtenancy.yourorganization.com/HdaApi/rest/v2.0/WorkItems/Delete

Example Request JSON

{
  "workItemIds": [
    "2d9f3d10-6fdb-494f-9929-955515c6f114",
    "3a7f3d10-6fdb-494f-9929-955515c6f115"
  ],
  "callbackUrl": "https://yourapp.com/api/deletion-callback",
  "callbackSecret": "mySecretKey123"
}
  

Example Response

Status: 202 Accepted

Callback Notification

{
  "status": "Partial Failure",
  "successfullyDeletedWorkItems": [
    {
      "workItemId": "a1b2c3d4-e5f6-7890-abcd-1234567890ab"
    },
    {
      "workItemId": "b2c3d4e5-f6a7-8901-bcde-2345678901bc"
    },
    {
      "workItemId": "c3d4e5f6-a7b8-9012-cdef-3456789012cd"
    }
  ],
  "failedToDeleteWorkItems": [
    {
      "workItemId": "d4e5f6a7-b8c9-0123-def0-4567890123de",
      "errorMessage": "Work item not found."
    },
    {
      "workItemId": "e5f6a7b8-c9d0-1234-ef01-5678901234ef",
      "errorMessage": "User does not have permission to delete this work item."
    },
  ]
} 

Using the Response Data

The callback response provides a list of successfully and unsuccessfully deleted work items. You can use this data to confirm which items were deleted and retry deletion for failed items.

Handling Non-Existent Work Items

If a work item included in the deletion request does not exist, whether because it is already marked for deletion or was never created, it will not be processed as a successful deletion. Instead, it will be included in the failedToDeleteWorkItems section of the callback response with an error message. This allows the deletion process to continue for valid work items.