How to Offboard device from Defender for Endpoint via API
Published: January 21, 2023 | Author: René Laas
This is a knowledgebase item. Hope it helps you out someday to offboard a device from Defender for Endpoint via API. Due a misconfiguration in Intune it could be that personal devices are onboarded in Defender for Endpoint as well. The Intune administrator changed the assignment and removed those devices.
But those personal devices will still create alerts and are included in the reports. You as a Defender for Endpoint administrator have decided to remove the personal devices as well.
There are several options available to offboard devices from Defender for Endpoint. Within Microsoft Intune, you can use a custom OMA-URI or a PowerShell script to offboard devices. But you cannot use this option because the devices are already removed from Intune.
Another method to offboard devices is to use the Defender for Endpoint API. Use this option only to offboard device that are not accessible or manageable like personal devices.
Note. Offboard device from Defender for Endpoint does not remove the device from the inventory. To remove those devices as well, you must wait till the retention period has expired. Maximum 180 days
How to offboard devices that are still manageable
- Onboard Windows devices using a local script | Microsoft Learn
- Onboard Windows devices to Defender for Endpoint using Intune | Microsoft Learn
- Onboard Windows devices to Microsoft Defender for Endpoint via Group Policy | Microsoft Learn
- Onboard Windows devices using Configuration Manager | Microsoft Learn
How to offboard device via API
- In the menu go to Devices under Assets
- Search for device that you want to offboard (in my case Endpoint)
- In the overview section or in the URL you will find the Device ID
- Copy the device ID
- In the menu click on Partners and APIs under Endpoints
- Click on API Explorer.
Note. This tenant is registered in Europe, if you have your tenant registered in another region, please make sure you do not copy and paste the URL, but use the URL from your region
- Enter the following URL in the API Explorer
- Change in the dropdown menu GET to POST.
- Add the following code to the API Explorer
"Comment": "Offboard device by Security Admin via EndpointCave KB item"
- Click on Run Query
- The API will returns with a Status 200 response, this means that the POST action have been successfully performed and the next time when the device become available/online, Defender for Endpoint will offboard the device automatically without notification or approval
Note. After 7 days the device will get an inactive state