---
title: Retire a Device
slug: epmm/v1web-service-api-guide/retire-a-device
createdAt: 2026-11-03T13:31:16.040Z
---

This API retires a device.  Devices are retired based on a unique device ID (uuid).

:::hint{type="info"}
You can use this API with ServiceNow.
:::

**Examples**:

https\://\<Ivanti EPMM>/api/v1/dm/devices/retire/ee8198d9-5d79-4961-94c4-e21bf04b2467?Reason=User%20replaced%20device

https\://\<Ivanti EPMM>/api/v1/dm/devices/retire/mac/38AA3C62BFAD?Reason=User%20replaced%20device

| 1. URI:<br />https\:///api/v1/dm/devices/retire/                | Device with the input device uuid is retired                                                                                                           |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Http Method:                                                    | PUT                                                                                                                                                    |
| Format:                                                         | xml, json                                                                                                                                              |
| Request:                                                        |                                                                                                                                                        |
| Device uuid                                                     | Required. Unique ID of the device. This ID can be retrieved in the response of other API calls, such as Device Registration or Get Device Details.     |
| Reason                                                          | Free form text field (512 character limit) to display reason why the device is being retired.                                                          |
|                                                                 |                                                                                                                                                        |
| 2. URI:<br />https\:///api/v1/dm/devices/retire/mac/            | Device with the input Wi-Fi MAC address is retired.                                                                                                    |
| Http Method:                                                    | PUT                                                                                                                                                    |
| Format:                                                         | xml, json                                                                                                                                              |
| Request:                                                        |                                                                                                                                                        |
| macAddress                                                      | Required.                                                                                                                                              |
| Reason                                                          | Free form text field (512 character limit) to display reason why the device is being retired.                                                          |
|                                                                 |                                                                                                                                                        |
| Response Status Code:                                           |                                                                                                                                                        |
| ‘404 – No Data Found’                                           | There is no data.                                                                                                                                      |
| ‘200 – OK’                                                      | Data is present and the response is returned.                                                                                                          |
| Response:                                                       |                                                                                                                                                        |
| \<deviceManagementWebServiceResponse>                           |                                                                                                                                                        |
| \<messages>                                                     |                                                                                                                                                        |
| \<message> Device is retired successfully.\</message>           | Status Message.<br />Success is shown if the method execution is successful.<br />A descriptive error message is shown if the method execution failed. |
| \</messages>                                                    |                                                                                                                                                        |
| \<deviceUuid>caba40e7-f56b-44aa-ac70-79e32e91adf8\</deviceUuid> | Unique device ID.                                                                                                                                      |
| \< /deviceManagementWebServiceResponse>                         |                                                                                                                                                        |
|                                                                 |                                                                                                                                                        |