Label Management
Get information on all labels
This call returns information on all labels.
Required Role
See Authentication 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:
|
Sample request and response
Request
curl -k -sS -u <userName>:<password> '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 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 <userName>:<password> '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 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"
See Get label usage information for more information. |
isESSearch | |
devices | |
deviceUuids | This call always returns 0 (zero) for deviceUuids. To find the deviceUuids, use Search for devices, for example, as follows: GET https://[Ivanti EPMM]/api/ v2/ devices?adminDeviceSpaceId =1&labelId=4&fields=common .os_version,common.uuid
|
type | |
rowType | |
assetId | |
assetName | |
Sample request and response
Request
curl -k -sS -u <userName>:<password> '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 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 <userName>:<password> -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 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 <userName>:<password> '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 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 <userName>:<password> --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 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
}