Data management

Remove devices from the Nexthink inventory in bulk using the Data management API. Submit a batch of devices identified by their UID and name. The API is asynchronous: it queues each valid device for deletion and returns a per-device scheduling status immediately.

Prerequisites

Before using the Data management API, ensure the following are in place:

1. API credentials: Create a set of API credentials in your Nexthink instance as described in the API Credentials documentation.

2. JWT permission scope: The API credential must include the nx_dataplatform_device_deletion_api permission scope.

Identifying devices

Each entry in the request requires two fields:

Field	Description
uid	Device UID assigned by the Nexthink Collector. Must be a valid UUID.
name	Device name as reported by the Nexthink Collector. Must not be blank.

To retrieve device UIDs, run an Investigation scoped to the devices you want to remove and export the result to CSV.

Request limits

A single request can contain a maximum of 100 devices. For larger deletions, split the list into batches of up to 100 and call the API once per batch.

Per-device status

The API validates each device independently. A malformed UID does not cause the entire batch to be rejected, it produces an INVALID status for that entry while the rest of the batch proceeds.

Status	Meaning
SCHEDULED	Device successfully queued for deletion.
INVALID	The device UID is malformed; this entry was skipped.
FAILED	A downstream error prevented this device from being scheduled.

The scheduledCount field in the response indicates how many devices were queued successfully.

Asynchronous deletion

A 202 Accepted response confirms that the valid devices have been queued. Actual removal from the Nexthink inventory happens asynchronously in the background. The response does not indicate whether the deletion has been completed.

Correlation headers

Pass an x-request-id header (UUID format) to correlate your calls with Nexthink support logs. The value is echoed back in the response. If you omit it, the API generates and returns one.

Header	Direction	Description
x-request-id	Request / Response	Client-supplied or server-generated correlation UUID.
x-trace-id	Response	W3C traceparent-derived trace identifier; falls back to x-request-id.

Error codes

HTTP status	Code	When
400	EMPTY_REQUEST	The devices array is empty or missing.
400	INVALID_REQUEST	Schema validation failed, for example, blank uid or name.
400	BATCH_SIZE_EXCEEDED	More than 100 devices submitted in a single request.
400	EMPTY_TENANT	Tenant context could not be resolved from the JWT claims.
401	—	Bearer token is missing or invalid.
403	FEATURE_NOT_ENABLED	The Data management API is not enabled for this tenant.
500	INTERNAL_ERROR	Unexpected server error. Provide the x-request-id value when contacting support.