---
title: Label Management
slug: epmm/v2-api-guide/label-management
createdAt: 2026-10-06T08:06:41.184Z
---
## Get information on all labels
This call returns information on all labels.
### Required Role
See [Authentication](docId\:hJ6Ul2Sz4DNsmnPJ-Fxl_) for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.
| Required Role |
| -------------------------------------------------------------------- |
| **Category:** Label Management
**Role Description:** View label |
### HTTP method
GET
### Request URI
/api/v2/labels/label\_summary
### Request parameters
| Parameter | Description | Sample Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ |
| adminDeviceSpaceId | **Required**
**Parameter Type:** Query
**Data Type:** Number
Device space ID of the administrator. | 1 |
| limit | **Parameter Type:** Query
**Data Type:** Number
**Min:** 0
Indicates the maximum number of entries to return. Must be at least 0 and no more than 200. | |
| offset | **Parameter Type:** Query
**Data Type:** Number
**Min:** 0
**Max:** 10,000,000
**Default:** 0
Indicates the index of the first entry to return. | |
| sortField | **Parameter Type:** Query
**Data Type:** String
**Min:** 1 character
**Max:** 320 characters
Name of the field to use for sorting. | |
| sortOrder | **Parameter Type:** Query
**Data Type:** String
**Default:** ASC
Indicates the order in which entries are returned. Values can be "ASC" or "DESC". | ASC |
### Response fields
| Field | Description |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| totalCount | The total number of entries that the query matched. |
| resultCount | The number of entries that are being returned. |
| hasMore | Indicates that there are more entries available. |
| results | An array of retrieved objects shown below. |
| id | |
| name | |
| description | |
| isStatic | |
| criteria | |
| deviceCount | |
| deviceSpaceId | |
| deviceSpaceName | |
| deviceSpacePath | |
| rowType | Values include:
- ADMIN: Created by an admin.
- SYSTEM: A pre-defined system label. |
### Sample request and response
### Request
`curl -k -sS -u : 'https://[Ivanti EPMM]/api/v2/labels/label_summary?adminDeviceSpaceId=1'`
### Response
\{
"totalCount": 10,
"resultCount": 10,
"hasMore": false,
"results": \[
\{
"id": -1,
"name": "All-Smartphones",
"description": "Label for all devices irrespective of OS",
"isStatic": false,
"criteria": "\\"common.retired\\"=false",
"deviceCount": 2,
"deviceSpaceId": 1,
"deviceSpaceName": "Global",
"deviceSpacePath": "/1/",
"rowType": "SYSTEM"
},
\{
"id": -10,
"name": "Android",
"description": "Label for all Android Phones.",
"isStatic": false,
"criteria": "\\"common.platform\\"=\\"Android\\" AND \\"common.retired\\"=false",
"deviceCount": 1,
"deviceSpaceId": 1,
"deviceSpaceName": "Global",
"deviceSpacePath": "/1/",
"rowType": "SYSTEM"
},
\{
"id": -6,
"name": "Company-Owned",
"description": "Label for all Company owned smartphones.",
"isStatic": false,
"criteria": "\\"common.owner\\"=\\"COMPANY\\" AND \\"common.retired\\"=false",
"deviceCount": 2,
"deviceSpaceId": 1,
"deviceSpaceName": "Global",
"deviceSpacePath": "/1/",
"rowType": "SYSTEM"
},
\{
"id": -5,
"name": "Employee-Owned",
"description": "Label for all Employee owned Smartphones.",
"isStatic": false,
"criteria": "\\"common.owner\\"=\\"EMPLOYEE\\" AND \\"common.retired\\"=false",
"deviceCount": 0,
"deviceSpaceId": 1,
"deviceSpaceName": "Global",
"deviceSpacePath": "/1/",
"rowType": "SYSTEM"
},
\{
"id": -4,
"name": "iOS",
"description": "Label for all iOS devices.",
"isStatic": false,
"criteria": "\\"common.platform\\"=\\"iOS\\" AND \\"common.retired\\"=false",
"deviceCount": 1,
"deviceSpaceId": 1,
"deviceSpaceName": "Global",
"deviceSpacePath": "/1/",
"rowType": "SYSTEM"
},
\{
"id": -11,
"name": "macOS",
"description": "Label for all macOS Devices.",
"isStatic": false,
"criteria": "\\"common.platform\\"=\\"macOS\\" AND \\"common.retired\\"=false",
"deviceCount": 0,
"deviceSpaceId": 1,
"deviceSpaceName": "Global",
"deviceSpacePath": "/1/",
"rowType": "SYSTEM"
},
\{
"id": -20,
"name": "Signed-Out",
"description": "Label for devices that are in a multi-user signed-out state.",
"isStatic": false,
"criteria": "\\"common.noncompliance\_reasons\\" = \\"LOGGED\_OUT\\" AND \\"common.retired\\"=false",
"deviceCount": 0,
"deviceSpaceId": 1,
"deviceSpaceName": "Global",
"deviceSpacePath": "/1/",
"rowType": "ADMIN"
},
\{
"id": -21,
"name": "tvOS",
"description": "Label for all tvOS Devices.",
"isStatic": false,
"criteria": "\\"common.platform\_name\\" STARTS WITH \\"AppleTV\\" AND \\"common.retired\\"=false",
"deviceCount": 0,
"deviceSpaceId": 1,
"deviceSpaceName": "Global",
"deviceSpacePath": "/1/",
"rowType": "SYSTEM"
},
\{
"id": -13,
"name": "Windows",
"description": "Label for all Windows devices.",
"isStatic": false,
"criteria": "(\\"common.platform\_name\\" = \\"Windows 8.1\\" OR \\"common.platform\_name\\" = \\"Windows 10\\" AND \\"windows\_phone.wp\_phone\\" = false) AND \\"common.retired\\" = false",
"deviceCount": 0,
"deviceSpaceId": 1,
"deviceSpaceName": "Global",
"deviceSpacePath": "/1/",
"rowType": "SYSTEM"
},
\{
"id": -12,
"name": "Windows Phone",
"description": "Label for all Windows Phone Devices.",
"isStatic": false,
"criteria": "(\\"common.platform\\" = \\"Windows Phone\\" OR \\"common.platform\_name\\" = \\"Windows 10\\" AND \\"windows\_phone.wp\_phone\\" = true) AND \\"common.retired\\" = false",
"deviceCount": 0,
"deviceSpaceId": 1,
"deviceSpaceName": "Global",
"deviceSpacePath": "/1/",
"rowType": "SYSTEM"
}
]
}
## Get label usage information
This call provides the usage summary of a label.
### Required Role
See [Authentication](docId\:hJ6Ul2Sz4DNsmnPJ-Fxl_) for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.
| Required Role |
| -------------------------------------------------------------------- |
| **Category:** Label Management
**Role Description:** View label |
### HTTP method
GET
### Request URI
api/v2/labels//label\_usage\_summary
### Request parameters
| Parameter | Description | Sample Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| adminDeviceSpaceId | **Required**
**Parameter Type:** Query
**Data Type:** Number
Device space ID of the administrator. | 1 |
| -labelId | **Required**
**Parameter Type:** Path
**Data Type:** Number
Note that you need to precede the value with a dash. | -11 |
### Response fields
| Field | Description |
| ---------------------------------------------- | ----------- |
| policies | |
| configs | |
| id | |
| name | |
| description | |
| applications | |
| deviceCount | |
| policyCount | |
| configCount | |
| userCount | |
| applicationCount | |
### Sample request and response
### Request
`curl -k -sS -u : 'https://[Ivanti EPMM]`/api/v2/labels/-11/label\_usage\_summary?adminDeviceSpaceId=1`'`
### Response
\{
"policies": \[ ],
"configs": \[ ],
"applications": \[ ],
"deviceCount": 1,
"policyCount": 0,
"configCount": 0,
"userCount": 1,
"applicationCount": 0
}
## Get information about a specific label
This call provides information about a specific label.
### Required Role
See [Authentication](docId\:hJ6Ul2Sz4DNsmnPJ-Fxl_) for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.
| Required Role |
| -------------------------------------------------------------------- |
| **Category:** Label Management
**Role Description:** View label |
### HTTP method
GET
### Request URI
/api/v2/labels/
### Request parameters
| Parameter | Description | Sample Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| adminDeviceSpaceId | **Required**
**Parameter Type:** Query
**Data Type:** Number
Device space ID of the administrator. | 1 |
| -labelId | **Required**
**Parameter Type:** Path
**Data Type:** Number
Note that you need to precede the value with a dash. | -11 |
### Response fields
| Field | Description |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| results | Array of the fields shown below. |
| uuid | |
| id | |
| principal | |
| deviceSpaceId | |
| deviceSpacePath | |
| name | |
| description | |
| state | |
| staticLabel | |
| searchCriteria | |
| query | |
| deviceCount | This call always returns 0 (zero) for the device count. To find out how many devices are using a specific label, use:
GET "https\://\[Ivanti EPMM]/api/v2/labels/-1/label\_usage\_summary?adminDeviceSpaceId=1"
- Replace \[Ivanti EPMM] with the URL to your MonbileIron Corre environment.
- Substitute -1 with the desired label id
- Subsitute the “1” in adminDeviceSpaceId with the desired device space id.
See [Get label usage information](docId\:LIYp-sHLqqefwKUQG4xiL) for more information. |
| isESSearch | |
| devices | |
| deviceUuids | This call always returns 0 (zero) for deviceUuids. To find the deviceUuids, use [Search for devices](docId\:gHOR_tm-Xo7xBWWPI6WRw), for example, as follows:
GET https\://\[Ivanti EPMM]/api/ v2/ devices?adminDeviceSpaceId =1\&labelId=4\&fields=common .os\_version,common.uuid
- Replace \[Ivanti EPMM] with the URL to your MonbileIron Corre environment.
- Substitute 4 with the desired label id
- Subsitute the “1” in adminDeviceSpaceId with the desired device space id. |
| type | |
| rowType | |
| assetId | |
| assetName | |
### Sample request and response
### Request
`curl -k -sS -u : 'https://[Ivanti EPMM]/`api/v2/labels/-11?adminDeviceSpaceId=1`'`
### Response
\{
"results": \{
"uuid": null,
"id": -11,
"principal": null,
"deviceSpaceId": 1,
"deviceSpacePath": "/1/",
"name": "OS X",
"description": "Label for all OS X Devices.",
"state": null,
"staticLabel": false,
"searchCriteria": \[],
"query": "\\"common.platform\\"=\\"OS X\\" AND \\"common.retired\\"=false",
"deviceCount": 0,
"isESSearch": "t",
"devices": \[],
"deviceUuids": null,
"type": "LABEL",
"rowType": "SYSTEM",
"assetId": "-11",
"assetName": "OS X"
}
}
## Add/Edit a label
This call adds a new label or updates an existing label. You should send `-H "Content-Type: application/json"` with this call.
### Required Role
See [Authentication](docId\:hJ6Ul2Sz4DNsmnPJ-Fxl_) for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.
| Required Role |
| ---------------------------------------------------------------------- |
| **Category:** Label Management
**Role Description:** Manage label |
### HTTP method
POST
### Request URI
/api/v2/labels
### Request parameters
| Parameter | Description | Sample Value |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| deviceSpaceId | **Required**
**Parameter Type:** Query
**Data Type:** Number
Device space ID of the administrator. | 1 |
| criteria | **Required**
**Parameter Type:** Request body
**Data Type:** String
Label criteria. | common.platform"="Android" AND "common.retired"=false |
| description | **Required**
**Parameter Type:** Request body
**Data Type:** String
Description of the label. | Label for all Android Phones. |
| labelId | Required if editing an existing label. Omit if adding a new label.
**Parameter Type:** Request body
**Data Type:** Number
Precede the label with a dash. | -10 |
| name | **Required**
**Parameter Type:** Request body
**Data Type:** Number
Name of the label. | Android |
| static | **Required**
**Parameter Type:** Request body
**Data Type:** Boolean
Determines whether the label is static. | false |
### Response fields
| Field | Description |
| ------------------------------------------------ | -------------------------------- |
| results | Array of the fields shown below. |
| uuid | |
| id | |
| principal | |
| deviceSpaceId | |
| deviceSpacePath | |
| name | |
| description | |
| state | |
| staticLabel | |
| searchCriteria | |
| query | |
| deviceCount | |
| isESSearch | |
| devices | |
| deviceUuids | |
| type | |
| rowType | |
| assetId | |
| assetName | |
### Sample request and response
### Request
Edit the label with labelId of -10:
curl `-k -sS -u : -H "Content-Type: application/json" `'https\://`[Ivanti EPMM]`/api/v2/labels/?adminDeviceSpaceId=1' --data-binary '\{
"name": "Android 2",
"description": "Label for all Android Phones.",
"deviceSpaceId": 1,
"static": false,
"criteria": "(\\"common.platform\\"=\\"Android\\") AND \\"common.retired\\"=false",
"labelId": "-10"
}'
### Response
\{
"results": \{
"uuid": null,
"id": -10,
"principal": "miadmin",
"deviceSpaceId": 1,
"deviceSpacePath": "/1/",
"name": "Android 2",
"description": "Label for all Android Phones.",
"state": null,
"staticLabel": false,
"searchCriteria": \[ ],
"query": "\\"common.platform\\"=\\"Android\\" AND \\"common.retired\\"=false",
"deviceCount": 0,
"isESSearch": "f",
"devices": \[ ],
"deviceUuids": null,
"type": "LABEL",
"rowType": "ADMIN",
"assetId": "-10",
"assetName": "Android 2"
}
}
## Delete a label
This call deletes a label.
### Required Role
See [Authentication](docId\:hJ6Ul2Sz4DNsmnPJ-Fxl_) for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.
| Required Role |
| ---------------------------------------------------------------------- |
| **Category:** Label Management
**Role Description:** Manage label |
### HTTP method
DELETE
### Request URI
/api/v2/labels
### Request parameters
| Parameter | Description | Sample Value |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| adminDeviceSpaceId | **Required**
**Parameter Type:** Query
**Data Type:** Number
Device space ID of the administrator. | 1 |
| -labelId | **Required**
**Parameter Type:** Request body
**Data Type:** Number
Note that you need to precede the value with a dash. | -11 |
| reason | **Parameter Type:** Request body
**Data Type:** String
Reason for deletion. | No longer needed. |
### Response
200 OK
### Sample request and response
### Request
curl `-k -sS -u : `'https\://`[Ivanti EPMM]`/rest/api/v2/labels/?adminDeviceSpaceId=1' -X DELETE --data-binary '\{"reason":"No longer needed","labelIds":\[-11]}'
### Response
200 OK
## Get list of applied/non-applied static labels for devices
This call gets a list of applied/non-applied static labels for devices.
### Required Role
See [Authentication](docId\:hJ6Ul2Sz4DNsmnPJ-Fxl_) for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.
| Required Roles |
| ---------------------------------------------------------------------- |
| **Category:** Label Management
**Role Description:** Manage label |
### HTTP method
POST
### Request URI
/api/v2/devices/labels
### Request parameters
| Parameter | Description | Sample Value |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| deviceSpaceId | **Required**
**Parameter Type:** Request body
**Data Type:** Number
Device space ID of the administrator. | 1 |
| entityIds | **Parameter Type:** Request body
**Data Type:** Number
A list of device ID for applied labels, empty for non-applied labels. | 1,98 |
| query | **Required**
**Parameter Type:** Request body
**Data Type:** String
Name or description of label. | Label for all Android Phones. |
| assignedOnly | Required if editing an existing label. Omit if adding a new label.
**Parameter Type:** Request body
**Data Type:** Boolean
**Default: **false
true to get only assigned labels, otherwise it returns both assigned or unassigned labels | false |
| limit | **Parameter Type:** Query
**Data Type:** Number
**Min:** 0
Indicates the maximum number of entries to return. Must be at least 0 and no more than 200. | |
| offset | **Parameter Type:** Query
**Data Type:** Number
**Min:** 0
**Max:** 10,000,000
**Default:** 0
Indicates the index of the first entry to return. | |
| sortField | **Parameter Type:** Query
**Data Type:** String
**Min:** 1 character
**Max:** 320 characters
Name of the field to use for sorting. | |
| sortOrder | **Parameter Type:** Query
**Data Type:** String
**Default:** ASC
Indicates the order in which entries are returned. Values can be "ASC" or "DESC". | ASC |
### Response fields
| Field | Description |
| ------------------------------------------------ | --------------------------------------------------- |
| totalCount | The total number of entries that the query matched. |
| resultCount | The number of entries that are being returned. |
| hasMore | Indicates that there are more entries available. |
| results | Array of the fields shown below. |
| uuid | |
| id | |
| principal | |
| deviceSpaceId | |
| deviceSpacePath | |
| name | |
| description | |
| state | |
| searchCriteria | |
| applied | |
| notApplied | |
| isESSearch | |
### Sample request and response
### Request
Edit the label with labelId of -10:
curl --globoff --user `:` --data '\{
"entityIds": \[
1,
98
],
"offset": 0,
"limit": 50,
"page": 1
}' --request POST 'https\://`[Ivanti EPMM]`/api/v2/devices/labels?adminDeviceSpaceId=1'
### Response
\{
"totalCount": 103,
"resultCount": 2,
"hasMore": true,
"results": \[
\{
"uuid": null,
"id": 3,
"principal": null,
"deviceSpaceId": 1,
"deviceSpacePath": null,
"name": "L1",
"description": "",
"state": "NOT\_APPLIED",
"searchCriteria": null,
"applied": \[ ],
"notApplied": \[
"100000000"
],
"isESSearch": "t"
},
\{
"uuid": null,
"id": 7,
"principal": null,
"deviceSpaceId": 1,
"deviceSpacePath": null,
"name": "L3",
"description": "",
"state": "NOT\_APPLIED",
"searchCriteria": null,
"applied": \[ ],
"notApplied": \[
"100000000"
],
"isESSearch": "t"
}
]
}
## Get list of labels for a specific device
This call gets a list of labels for a specific device.
### Required Role
See [Authentication](docId\:hJ6Ul2Sz4DNsmnPJ-Fxl_) for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.
| Required Roles |
| ------------------------------------------------------------------------------------------- |
| **Category:** Device Management
**Role Description:** View device page, device details |
| **Category:** Label Management
**Role Description:** View label |
### HTTP method
GET
### Request URI
/api/v2/devices//labels?adminDeviceSpaceId=
### Request parameters
| Parameter | Description | Sample Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| adminDeviceSpaceId | **Required**
**Parameter Type:** Query
**Data Type:** Number
Device space ID of the administrator. | 1 |
| deviceGuid | **Parameter Type:** Path
**Data Type:** String
Device GUID of the device for which to get label information. | 9624b93e-ddb4-48d1-aea3-d2f0084b6b4d |
### Response fields
| Field | Description |
| ------------------------------------- | ----------- |
| messages | |
| localizedMessage | |
| messageKey | |
| messageParameters | |
| type | |
| resultCount | |
| results | |
| description | |
| id | |
| name | |
| query | |
| staticLabel | |
| totalCount | |
### Sample request and response
### Request
$ curl --user jsmith\:Ab8fit28 --request GET 'https\://*\[Ivanti EPMM]*/api/v2/devices/1234b93e-ddb4-48d1-aea3-d2f0084b6b4d/labels?adminDeviceSpaceId=1
### Response
\{
"messages": \[
\{
"localizedMessage": "4 Label(s) returned.",
"messageKey": "com.mobileiron.vsp.rest.controllers.LabelControllerV2.Messages.LABELS\_FOUND",
"messageParameters": \[
4
],
"type": "Info"
}
],
"resultCount": 4,
"results": \[
\{
"description": "Label for all Android Phones.",
"id": -10,
"name": "Android",
"query": "\\"common.platform\\"=\\"Android\\" AND \\"common.retired\\"=false",
"staticLabel": false
},
\{
"description": "Label for all Company owned smartphones.",
"id": -6,
"name": "Company-Owned",
"query": "\\"common.owner\\"=\\"COMPANY\\" AND \\"common.retired\\"=false",
"staticLabel": false
},
\{
"description": "Label for all devices irrespective of OS",
"id": -1,
"name": "All-Smartphones",
"query": "\\"common.retired\\"=false",
"staticLabel": false
},
\{
"description": "",
"id": 3,
"name": "android\_static",
"query": null,
"staticLabel": true
}
],
"totalCount": 4
}