Device Management

Search for devices

This call returns information about devices. There are three ways to get device information: filtered by a search query, filtered by label, or filtered by both a search query and a label. This call has a GDPR consideration. See GDPR Consideration.

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: Device Management

Role Description: View dashboard, device page, device details

HTTP method

GET

Request URI

api/v2/devices

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

query

Required: One of either the query or labelId parameters is required, and you can use both in the same call, but not both with an advanced query. See Supported queries for more information.

Parameter Type: Query

Data Type: String

Min: 0 character

Max: 255 characters

Search expression. An empty query returns everything. See Query Operators and Search Fields for complete details on the query operators and search fields you can use to construct the query parameter statement.

 

labelId

Required: One of either the labelId or query parameter is required, and you can use both in the same call. See Supported queries for more information.

Parameter Type: Query

Data Type: Number

The Label ID.

 

fields

Required

Parameter Type: Query

Data Type: List of strings

Min: 1 field

Max: 512 fields

Comma-separated list of the names of fields to be returned; Each field should be no more than 320 characters long. See Valid fields Parameter Values for a list of valid values, and Get the list of searchable device fields for how to query for the values. See Supported queries for more information.

user.display_name%2Ccommon.current_phone_number

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

Supported queries

The following table describes the supported and unsupported query formats. Any deviation from the query formats noted as “supported” is unsupported.

 

API Call

Supported?

Sample Request

Sample Response

Only simple query

Unsupported

https://[Ivanti EPMM]/api/v2/devices?adminDeviceSpaceId=1&fields=common.os_version,common.uuid&query=test

{

    "messages": [

        {

            "type": "Error",

            "messageKey": "com.mobileiron.vsp.messages.advancedsearch.parse.failure",

            "localizedMessage": "Unrecognized token '<EOF>' at position 4",

            "messageParameters": [

                "<EOF>",

                4

            ]

        }

    ]

}

Simple query & label

Supported

https://[Ivanti EPMM]/api/v2/devices?adminDeviceSpaceId=1&fields=common.os_version,common.uuid&labelId=4&query=test

{

    "results": [

        {

            "common.os_version": "12.1.2",

            "common.uuid": "c592e4f3-4e76-4148-a91e-c62da8464968"

        }

    ],

    "totalCount": 1,

    "resultCount": 1,

    "searchTimeMillis": 11,

    "currentServerTimeMilliseconds": 1551852839417,

    "hasMore": false

}

Advanced search

Supported

https://[Ivanti EPMM]/api/v2/devices?adminDeviceSpaceId=1&fields=common.os_version,common.uuid&query="common.uuid"="c592e4f3-4e76-4148-a91e-c62da8464968"

{

    "results": [

        {

            "common.os_version": "12.1.2",

            "common.uuid": "c592e4f3-4e76-4148-a91e-c62da8464968"

        }

    ],

    "totalCount": 1,

    "resultCount": 1,

    "searchTimeMillis": 3,

    "currentServerTimeMilliseconds": 1551852943226,

    "hasMore": false

}

Label & advanced query

Unsupported

https://[Ivanti EPMM]/api/v2/devices?adminDeviceSpaceId=1&fields=common.os_version,common.uuid&labelId=4&query="common.uuid"="c592e4f3-4e76-4148-a91e-c62da8464968"

{

    "results": [],

    "totalCount": 0,

    "resultCount": 0,

    "searchTimeMillis": 133,

    "currentServerTimeMilliseconds": 1551853012054,

    "hasMore": false

}

Only label

Supported

https://[Ivanti EPMM]/api/v2/devices?adminDeviceSpaceId=1&labelId=4&fields=common.os_version,common.uuid

{

    "results": [

        {

            "common.os_version": "12.1.2",

            "common.uuid": "c592e4f3-4e76-4148-a91e-c62da8464968"

        }

    ],

    "totalCount": 1,

    "resultCount": 1,

    "searchTimeMillis": 3,

    "currentServerTimeMilliseconds": 1551853076127,

    "hasMore": false

}

Response fields

Field

Description

results

An array of retrieved objects. Each object includes just the fields requested with the fields parameter.

        common.ip_address

The device’s IP address, for example, 10.11.103.146.

        common.os_version

The device’s OS version, for example, 4.4.

        common.platform_name

The device's platform name and OS version, for example, Android 4.4.

        common.locale

The locale, for example, en-US.

        common.storage_capacity

The device’s storage capacity in bytes, for example, 11766960000.

        common.miclient_last_connected_at

When the client last connected to Ivanti EPMM, for example, 2016-07-11T19:19:26.000Z.

        common.home_operator_name

Operator of the device, for example, AT&T.

        common.uuid

The device’s UUID, for example, a57dcd91-f9a4-428e-bd47-3dd96bb7e1f9. It is the internal identifier for the device.

        common.quarantined

Boolean. True or false, is the device quarantined.

        common.id

The internal ID number of the device in Ivanti EPMM.

        common.device_space_name

The name of the device space to which the device belongs. “Global” is the name of the default main device space.

        common.ccm_migration_status

Displays status of the device’s migration from Ivanti EPMM to Cloud.

        common.imsi

The international mobile subscriber identity of the device, for example, 310410792173128. This is a unique number identifying a GSM subscriber.

        common.ccm_migration_status

Displays status of the device’s migration from Ivanti EPMM to Cloud.

        android.afw_capable

Boolean. True or false, is the device Apps for Work capable.

        common.storage_free

How much free storage in bytes is there on the device, for example, 9754620000.

        common.device_is_compromised

Boolean. True or false, is the device compromised.

        common.owner

The device owner, often the company that owns the device.

        custom.device.attribute_name

Name of the custom value attribute and its corresponding value.

        user.email_address

Email address of the device’s user.

        common.manufacturer

Device manufacturer, for example, Samsung.

        common.data_protection_enabled

Boolean. True or false, is the device data protection enabled.

        common.mdm_managed

Boolean. True or false, is the device managed by a mobile device management system.

        common.memory_free

How much free memory in bytes does the device have, for example, 615304396.

        common.model

The model name of the device, for example, SAMSUNG-SM-G900A.

        common.memory_capacity

How much memory in bytes does the device have, for example, 1946943488.

        common.client_name

The bundle name of the client on the device, for example, com.mobileiron.

        common.status

Status of the device, for example, ACTIVE, PENDING, RETIRED.

        common.current_phone_number

Phone number of the device.

        common.platform

Platform of the device, for example, Android.

        common.imei

International Mobile Station Equipment Identity of the device, for example, 354691065438150. Used to identify 3GPP and iDEN mobile phones, as well as some satellite phones.

        user.display_name

Name of the user associated with the device.

        common.creation_date

Date the corresponding account was created, for example, 2016-07-11T19:18:13.000Z.

        android.attestation

The attestation status of the device, for example, UNKNOWN.

        common.background_status

The background status of the device, for example, 0.

        common.last_connected_at

The time and date of the last MDM checkin of the device, for example, 2016-07-11T19:19:26.000Z.

        common.home_country_name

Cellular home country of the device, for example, United States.

        android.registration_status

Registration level of the device user, for example, Device Admin.

        common.battery_level

Remaining power level of the device’s battery, for example, 100.

        common.client_version

The version of the client app on the device, for example, 9.0.1.0.68D.

        common.language

The device’s language, for example, English.

        user.user_id

ID of the user associated with the device, for example, testuser2264.

        common.compliant

Boolean. True or false, is the device compliant.

        common.registration_date

Date that the device registered with Ivanti EPMM, for example, 2016-07-11T19:19:26.000Z.

        common.device_admin_enabled

Boolean. True or false, is the device MDM managed. For Android, this means the client app is set as a Device Admin. For iOS, this means the MDM certificate is installed on the device.

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.

Sample request and response

Request

Search for smart phones with “Samsung” in their name.

{noformat}

curl 'https://[Ivanti EPMM]/admin/rest/api/v2/devices?count=50&offset=0&sortOrder=ASC&sortField=user.display_name&fields=user.display_name,common.current_phone_number,common.model,common.manufacturer,common.mdm_managed,common.platform_name,common.home_country_name,common.registration_date,common.last_connected_at,common.miclient_last_connected_at,common.owner,common.home_operator_name,common.language,common.creation_date,common.uuid,common.clientId,user.email_address,common.comment,user.user_id,common.storage_capacity,common.device_is_compromised,common.noncompliance_reasons,common.compliant,common.platform,common.quarantined,common.quarantined_reasons,common.id,android.attestation,ios.wakeup_status,common.status,common.device_space_name,common.background_status,common.data_protection_enabled,common.data_protection_reasons,common.device_admin_enabled,common.memory_capacity,common.memory_free,common.storage_capacity,common.storage_free,common.battery_level,common.client_name,common.client_version,ios.DataRoamingEnabled,common.locale,common.ethernet_mac,common.imei,common.imsi,common.ip_address,ios.iPhone ICCID,ios.iPhone MAC_ADDRESS_EN0,ios.iPhone UDID,ios.iPhone VERSION,ios.DeviceName,common.os_version,android.afw_capable,android.registration_status&labelId=-1&query=samsung&page=1&start=0&limit=50' -H 'authUserId: bWlhZG1pbg=='

{noformat}

Response

{

    "results": [

        {

            "common.ip_address": "10.11.103.146",

            "common.os_version": "4.4",

            "common.platform_name": "Android 4.4",

            "common.locale": "en-US",

            "common.storage_capacity": 11766960000,

            "common.miclient_last_connected_at": "2016-07-11T19:19:26.000Z",

            "common.home_operator_name": "AT&T",

            "common.uuid": "a57dcd91-f9a4-428e-bd47-3dd96bb7e1f9",

            "common.quarantined": false,

            "common.id": 9,

            "common.device_space_name": "Global",

            "common.ccm_migration_status": "None",

            "common.imsi": "310410792173128",

            "android.afw_capable": false,

            "common.storage_free": 9754620000,

            "common.device_is_compromised": false,

            "common.owner": "COMPANY",

            "user.email_address": "[email protected]",

            "common.manufacturer": "samsung",

            "common.data_protection_enabled": true,

            "common.mdm_managed": false,

            "common.memory_free": 615304396,

            "common.model": "SAMSUNG-SM-G900A",

            "common.memory_capacity": 1946943488,

            "common.client_name": "com.mobileiron",

            "common.status": "ACTIVE",

            "common.current_phone_number": "PDA",

            "common.platform": "Android",

            "common.imei": "354691065438150",

            "user.display_name": "testuser2264",

            "common.creation_date": "2016-07-11T19:18:13.000Z",

            "android.attestation": "Unknown",

            "common.background_status": 0,

            "common.last_connected_at": "2016-07-11T19:19:26.000Z",

            "common.home_country_name": "United States",

            "android.registration_status": "Device Admin",

            "common.battery_level": 100,

            "common.client_version": "9.0.1.0.68D",

            "common.language": "English",

            "user.user_id": "testuser2264",

            "common.compliant": true,

            "common.registration_date": "2016-07-11T19:19:26.000Z",

            "common.device_admin_enabled": true

        }

    ],

    "totalCount": 1,

    "resultCount": 1,

    "searchTimeMillis": 51,

    "currentServerTimeMilliseconds": 1468265055060,

    "hasMore": false

}

Self-register a device

This call enables a user to self-register a device on the user portal.

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: Device Management

Role Description: Manage devices, restricted

HTTP method

POST

Request URI

api/v2/users/register_device

Request parameters

Parameter

Description

Sample Value

countryCode

Required

Parameter Type: Request body

Data Type: Integer

Country code of target device.

1

deviceLanguageId

Parameter Type: Request body

Data Type: Long

Language of target device.

1

isPhoneNumberAvailable

Required

Parameter Type: Request body

Data Type: Boolean

true or false.

false

isForceRegister

Parameter Type: Request body

Data Type: Boolean

true or false. Specify whether to force registration.

false

notifyUser

Parameter Type: Request body

Data Type: Boolean

Specify whether to notify the user. true or false. Default is true.

true

operatorId

Required

Parameter Type: Request body

Data Type: Long

Carrier ID.

269

phoneNumber

Parameter Type: Request body

Data Type: String

Device phone number

5555555555

platform

Required

Parameter Type: Request body

Data Type: String

Device type

I

Response fields

Field

Description

results

Container for results.

passcode

Device passcode.

ttl

Passcode expiration date.

regLink

Registration URL.

email

Email for device owner.

totalCount

Number of matching items.

resultCount

Number of returned results.

Sample request

curl -kv -u username:password -H "Content-Type: application/json" --data '{"countryCode": 1, "deviceLanguageId": 1, "isForceRegister": "false", "isPhoneNumberAvailable": "true", "notifyUser": "true", "operatorId": 269, "phoneNumber": "4083338888", "platform": "I"}' -XPOST 'https://[Ivanti EPMM]/api/v2/users/register_device';

Sample response

 {
	"results": [
		{
		"passcode": "600698",
		"ttl": "120",
		"regLink": "http://[Ivanti EPMM]:8080/mifs/c/d/ios.html",
		"email": "[email protected]"
		}
	],
	"totalCount": 1,
	"resultCount": 1
}

Act on a device

This call performs one of the following actions on a device:

ENABLE_VOICE_ROAMING (iOS)

DISABLE_VOICE_ROAMING (iOS)

ENABLE_DATA_ROAMING (iOS)

DISABLE_DATA_ROAMING (iOS)

ENABLE_PERSONAL_HOTSPOT (iOS)

DISABLE_PERSONAL_HOTSPOT (iOS)

SEND_MESSAGE (Android, iOS)

UPDATE_OS (iOS)

UNLOCK_APP_CONNECT_CONTAINER (Android)

UNLOCK_DEVICE_ONLY (Android, iOS)

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: Device Management

Role Description: Manage devices, restricted

HTTP method

POST

Request URI

api/v2/devices/action

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

actionType

Required

Parameter Type: Query

Data Type: String

The action to perform.

One of:

ENABLE_VOICE_ROAMING (iOS)

DISABLE_VOICE_ROAMING (iOS)

ENABLE_DATA_ROAMING (iOS)

DISABLE_DATA_ROAMING (iOS)

ENABLE_PERSONAL_HOTSPOT (iOS)

DISABLE_PERSONAL_HOTSPOT (iOS)

SEND_MESSAGE (Android, iOS)

UPDATE_OS (iOS)

UNLOCK_APP_CONNECT_CONTAINER (Android)

UNLOCK_DEVICE_ONLY (Android, iOS)

ENABLE_VOICE_ROAMING

deviceUuids

Required

Parameter Type: Request body

Data Type: Array of UUID Strings

UUID Strings of the devices on which to perform the action.

a2556e62-2ed0-4d42-98fd-a342eaf3e4e6

note

Parameter Type: Request body

Data Type: String

Min: 1 character

Max: 200 characters

Note describing the action.

Turning off voice roaming.

Additional request parameters for send_message

Parameter

Description

Sample Value

note

Parameter Type: Request body

Data Type: String

Note about the message being sent.

Alerting owner to policy violation.

additionalParameters

Required

Parameter Type: Request body

Data Type: String

Container for the following additional parameters:

message

mode

subject

app

"additionalParameters" : {"message" : "Your device is in policy violation.","mode" : "sms","subject":"Important message","app" : "Motorola MC75"}

message

Required

Parameter Type: Request body

Data Type: String

Message to send.

Your device is in policy violation.

mode

Required

Parameter Type: Request body

Data Type: String

Mode of transmission for the message.

Valid values:

sms

pns

email

sms

subject

Required

Parameter Type: Request body

Data Type: String

Subject of the message.

Important news about your device

Response fields

Field

Description

actionType

The action that was successful.

deviceResults

A map of "device-uuid":"status", where the status describes whether the action succeeded or why it failed.

successful

Returns “true” if the action is successful on all devices, or “false” if the action is not successful on one or more devices.

Sample request and response

Request

Enable data roaming.

curl -k -sS -u <userName>:<password> -v -XPOST 'https://[Ivanti EPMM]/api/v2/devices/action?adminDeviceSpaceId=1&actionType=ENABLE_VOICE_ROAMING' -d '{ "deviceUuids": ["a2556e62-2ed0-4d42-98fd-a342eaf3e4e6","aa0a05dc-14c9-4355-9640-406b5c219c06","d427879e-bdce-469a-810e-d38eef39bf8e"], "note" : "sample note" }' -H 'Content-Type:application/json'

Response

{

    "actionType": "ENABLE_VOICE_ROAMING",

    "deviceResults": {

        "a68bb0cf-7a35-4d52-8259-c83398a41160": "com.mobileiron.vsp.messages.device.action.successful"

    },

    "successful": true

}

Request

Send message

curl -k -sS -u <userName>:<password> -v -XPOST 'https://[Ivanti EPMM]/api/v2/devices/action?adminDeviceSpaceId=1&actionType=SEND_MESSAGE' -d '{ "deviceUuids": ["db46d2ca-df92-46d6-807e-8eb014e28a6f"], "note" : "Alerting owner to policy violation.", "additionalParameters" : {"message" : "Your device is in policy violation","mode" : "sms","subject":"Important news about your device","app" : "Motorola MC75"} }' -H 'Content-Type:application/json'

Response

{

"actionType"": ""SEND_MESSAGE"

"deviceResults"": {

"db46d2ca-df92-46d6-807e-8eb014e28a6f"": ""com.mobileiron.vsp.messages.device.action.successful""

}-

"successful"": true

}

Export devices

This call returns a CSV file for all devices found by the search. Use the fieldGroups parameter to specify a list of field groups to be returned in the CSV file.

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: Device Management

Role Description: View dashboard, device page, device details

HTTP method

POST

Request URI

api/v2/devices

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

query

Required: One of either the query or labelId parameters is required, and you can use both in the same call.

Parameter Type: Query

Data Type: String

Min: 0 character

Max: 2000 characters

Search expression. An empty query returns everything. See Query Operators and Search Fields for complete details on the query operators and search fields you can use to construct the query parameter statement.

 

labelId

Required: One of either the labelId or query parameter is required, and you can use both in the same call.

Parameter Type: Query

Data Type: Number

The Label ID.

 

fieldGroups

Required

Parameter Type: Query

Data Type: List of strings

Min: 1 field group

Max: 20 field groups

Comma-separated list of the names of field groups to be returned. Each field group should be no more than 20 characters long. May be any sequence of the following group names: "BASIC", "COMMON", "ANDROID", "IOS", "USER", "WINDOWS_PHONE"

USER,COMMON,ANDROID,IOS,WINDOWS_PHONE

limit

Parameter Type: Query

Data Type: Number

Min: 0

Max: 2000

Default: 2000

Indicates the maximum number of entries to return.

 

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 values

Content-Type: text/csv

Content-Disposition: attachment; filename= DeviceSearchResult.csv

Sample request and response

Request

curl "https://[Ivanti EPMM]/api/v2/devices?fieldGroups=USER"%"2CCOMMON"%"2CANDROID"%"2CIOS"%"2CWINDOWS_PHONE&labelId=-10&query=" -H "Content-type: application/json" --data "authUserId=bWlhZG1pbg"%"3D"%"3D"

Response

Response is a CSV file containing the retrieved values.

Delete devices

This call deletes retired iOS, OS X, Win8, or Android devices that have not been modified in the last day.

Required Role

 

Required Role

Category: Device Management

Role Description: Delete retired device (API only)

HTTP method

DELETE

Request URI

api/v2/devices

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

 

deviceUuids

Parameter Type: Request body

Data Type: Array of strings

Min: 1 deviceUuid

Max: 512 deviceUuids

Comma-separated list of device uuids to delete if retired and is of platform iOS, OS X, Win8, Android.

10c43352-15b2-413b-a3e0-4daf3977711a

wifiMacs

Parameter Type: Request body

Data Type: Array of strings

Min: 1 wifiMacs

Max: 512 wifiMacs

Comma-separated list of wifiMacs to delete if retired and is of platform iOS, OS X, Win8, Android.

2a393b114f7c

principals

Parameter Type: Request body

Data Type: Array of strings

Min: 1 principals

Max: 512 principals

Comma-separated list of principals to delete if retired and is of platform iOS, OS X, Win8, Android.

 

Response object

A JSON object containing the following fields:

Field

Description

(unnamed}

An array of the UUIDs of those devices that were eligible to be deleted. An empty list means no devices deleted.

Sample request and response

Request

curl -k -sS -u username:password -XDELETE -H "Content-Type: application/json" 'https://[Ivanti EPMM]/api/v2/devices?adminDeviceSpaceId=1' -d '{ "deviceUuids" : [ "10c43352-15b2-413b-a3e0-4daf3977711a", "B0BAB9BA-388E-4612-B579-43A40411670C" ] }'

Response

Only the first UUID was returned because it met the criteria for deletion. The second UUID was not deleted, either because it was not retired, it had been modified within the last day, or it was not of the correct platform.

[

    "10c43352-15b2-413b-a3e0-4daf3977711a"

]

 

Count devices

This call returns the count of devices that match the specified query.

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: Device Management

Role Description: View dashboard, device page, device details

HTTP method

GET

Request URI

api/v2/devices/count

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

adminDeviceSpaceId=1

query

Required

Parameter Type: Query

Data Type: Number

Min: 0 characters

Max: 2000 characters

Search expression. An empty query returns the count of all devices. See Query Operators and Search Fields for complete details on the query operators and search fields you can use to construct the query parameter statement.

query="common.manufacturer" starts with "Appl"

Response fields

Field

Description

totalCount

The total number of entries that the query matched.

Sample request and response

Request

Count all devices that are manufactured by Apple.

curl -X GET -H "Authorization: Basic <token>" https://[Ivanti EPMM]]/api/v2/devices/count?adminDeviceSpaceId=1&query="common.manufacturer" starts with "Appl"

Response

{

    "totalCount": 117

}

Test an advanced search query

This call tests that the device-search query parses correctly.

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: Device Management

Role Description: View dashboard, device page, device details

HTTP method

GET

Request URI

api/v2/devices/query_test

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

adminDeviceSpaceId=1

query

Required

Parameter Type: Query

Data Type: Number

Min: 0 characters

Max: 2000 characters

Search expression. An empty query is valid. See Query Operators and Search Fields for complete details on the query operators and search fields you can use to construct the query parameter statement.

query=manufacturer contains "Apple"

Response fields

Field

Description

valid

True if the query was valid; false otherwise.

token

Represents the offending token if the query was invalid; the empty string otherwise.

position

The index of the first character of the offending token relative to the beginning of the line in which it occurs, 0..n-1; -1 otherwise.

Sample request and response

Request

Validate the query.

curl -G -k -sS -u username:password 'https://[Ivanti EPMM]/api/v2/device/query_test' --data 'query%3Dmanufacturer%20contains%20%22blargle%22'

Response

{

    "valid": false,

    "token": "blargle",

    "position": 21

}

Get the list of searchable device fields

This call gets the name and type of device, details, and LDAP fields. You can use this information to find values for the fields parameter for any of the API calls that allow specification of search fields, such as Search 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 Role

Category: Device Management

Role Description: View dashboard, device page, device details

HTTP method

GET

Request URI

api/v2/devices/search_fields

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

 

Response fields

An array of field-name-to-data-type objects:

Field

Description

name

The name of the field, which may be prefixed with the group to which the field belongs. For example, "detail.APNS Capable" or "ldap.user.first_name".

type

The data type of the field, which could be "STRING", "NUMBER", or "DATE".

Sample request and response

Request

Get the fields.

curl -G -k -sS -u username:password 'https://[Ivanti EPMM]/api/v2/device/search_fields'

 

Response

[

        { "name" : "uuid", "type" : "STRING" },

        { "name" : "block_reason", "type" : "NUMBER" },

        { "name" : "last_connected_at", "type" : "DATE" },

        { "name" : "details.APNS Capable", "type" : "STRING" },

        { "name" : "ldap.user.baseDn", "type" : "STRING" }

]

Get device details

This call gets device details 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 Role

Category: Device Management

Role Description: View dashboard, device page, device details

HTTP method

GET

Request URI

api/v2/devices/<deviceId>/details

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

 

deviceId

Required

Parameter Type: Path

Data Type: String

The deviceId is the device UUID.

2e33329d-fed5-4f56-a2b7-65caa5ef0cfe

Response fields

Field

Description

results

Container for the array of detail objects returned.

totalCount

The total number of entries that the query matched.

resultCount

The number of entries that are being returned.

Sample request and response

Request

curl "https://[Ivanti EPMM]/api/v2/devices/2e33329d-fed5-4f56-a2b7-65caa5ef0cfe/details -H "authUserId: username" -H "Accept: application/json"

Response

{

    results: [

        {

            name: "ios.ProductName",

            value: null

        },

        {

            name: "common.current_operator_name",

            value: null

        },

        {

            name: "ios.security_reason_code",

            value: "0x00000008"

        },

        {

            name: "common.registration_imsi",

            value: "310410"

        },

       ... {

            name: "ios.BluetoothMAC",

            value: null

        },

        {

            name: "ios.IsDeviceLocatorServiceEnabled",

            value: false

        }

    ],

    totalCount: 84,

    resultCount: 84

}

Include battery health information in Android device details

This call includes battery health information in Android device details.

Additional battery health statistics per-device includes:

  • Android Battery Charging Status

  • Android Battery Health Status

  • Battery Charge Cycles (OEM)*

  • Battery Health Percentage (OEM)*

  • Battery Manufacture Date (OEM)*

*The OEM fields only populate if the device is a Zebra 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 Role

Category: Device Management

Role Description: View dashboard, device page, device details

HTTP method

GET

Request URI

api/v2/devices/<deviceId>/details?command=deviceDetail&deviceId=<deviceId>&os=<os version>&isBatteryStatsRequired=[true|false]

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

 

deviceId

Required

Parameter Type: Path

Data Type: String

The deviceId is the device UUID.

9af85060-4775-4f52-967c-bfb4979bd19d

command

Required

Parameter Type: Query

Data Type: String

Command to evaluate. Use deviceDetail.

command=deviceDetail

os

Required

Parameter Type: Query

Data Type: String

OS to evaluate, for example, os=Android%2012L for Android 12L.

os=Android%2012L

isBatteryStatsRequired

Parameter Type: Query

Data Type: boolean

use true to include battery information.

9af85060-4775-4f52-967c-bfb4979bd19d

Response fields

Field

Description

results

Container for the array of detail objects returned.

totalCount

The total number of entries that the query matched.

resultCount

The number of entries that are being returned.

Sample request and response

Request

https://[Ivanti EPMM]/api/v2/devices/9af85060-4775-4f52-967c-bfb4979bd19d/details?command=deviceDetail&deviceId=9af85060-4775-4f52-967c-bfb4979bd19d&os=Android%2012L&isBatteryStatsRequired=true

Response

{ "results": [ { "name": "android.wifi_inventory_mac_addr", "value": null }, { "name": "common.locale", "value": "en-US" }, { "name": "android.zebra_build_id", "value": null }, { "name": "common.sd_card_encrypted", "value": false }, { "name": "common.client_id", "value": 1073741834 }, { "name": "android.battery_zebra_total_cumulative_charge", "value": null }, { "name": "android.battery_zebra_bkvoltage", "value": null }, { "name": "android.battery_zebra_seconds_since_first_use", "value": null }, { "name": "common.imsi", "value": "" }, { "name": "android.afw_capable", "value": true }, { "name": "android.admin_activated", "value": true }, { "name": "common.mdm_managed", "value": false }, { "name": "android.secure_apps_encryption_enabled", "value": false }, { "name": "android.platform_flags", "value": "0x143" }, { "name": "android.battery_zebra_health_percentage", "value": null }, { "name": "common.creation_date", "value": "2022-07-05T07:34:05.000Z" }, { "name": "common.background_status", "value": 0 }, { "name": "common.EnhancedLoggingEnabled", "value": false }, { "name": "android.android_automated_enrollment", "value": "Unknown" }, { "name": "common.last_connected_at", "value": "2022-07-05T07:45:27.000Z" }, { "name": "android.battery_zebra_partnumber", "value": null }, { "name": "android.battery_health", "value": null }, { "name": "android.mdm_enabled", "value": true }, { "name": "android.battery_zebra_time_to_full", "value": null }, { "name": "android.codename", "value": null }, { "name": "common.client_version", "value": "11.6.0.1.1R" }, { "name": "common.ethernet_mac", "value": null }, { "name": "common.mtd_status", "value": "N/A" }, { "name": "android.battery_zebra_ratedcapacity", "value": null }, { "name": "android.prv_enable_network_slicing", "value": false }, { "name": "android.os_build_number", "value": "SQ3A.220605.009.B1" }, { "name": "android.security_detail", "value": "0" }, { "name": "android.multi_mdm", "value": false }, { "name": "common.device_admin_enabled", "value": true }, { "name": "common.location_last_captured_at", "value": null }, { "name": "common.os_version", "value": "12L" }, { "name": "common.intune_compliance_azure_tenant_id", "value": null }, { "name": "common.mdm_tos_accepted_date", "value": null }, { "name": "android.safety_net_status", "value": "None" }, { "name": "common.uuid", "value": "9af85060-4775-4f52-967c-bfb4979bd19d" }, { "name": "android.samsung_carrier_code", "value": null }, { "name": "android.secure_apps_encryption_mode", "value": null }, { "name": "common.display_size", "value": "2240X1080" }, { "name": "android.aosp_device", "value": "no" }, { "name": "android.iccid", "value": "" }, { "name": "common.device_is_compromised", "value": false }, { "name": "user.email_address", "value": null }, { "name": "android.safety_net_timestamp", "value": null }, { "name": "android.dualdar_enabled", "value": false }, { "name": "android.brand", "value": "google" }, { "name": "android.battery_status", "value": null }, { "name": "common.client_name", "value": "com.mobileiron" }, { "name": "common.imei", "value": "" }, { "name": "android.os_update_status", "value": null }, { "name": "user.last_name", "value": null }, { "name": "user.display_name", "value": "miadmin" }, { "name": "android.zebra_patch_version", "value": null }, { "name": "android.file_encryption", "value": true }, { "name": "android.developer_mode", "value": false }, { "name": "android.safety_net_result_exception", "value": "" }, { "name": "android.zebra_artifact_fingerprint", "value": null }, { "name": "common.registration_imsi", "value": null }, { "name": "android.manufacturer_os_version", "value": "12" }, { "name": "android.battery_zebra_time_to_empty", "value": null }, { "name": "user.uuid", "value": "bc4202db-ae47-4963-b207-24157b3a5df8" }, { "name": "android.battery_zebra_present_capacity", "value": null }, { "name": "android.usb_debugging", "value": false }, { "name": "android.battery_zebra_decommission", "value": null }, { "name": "common.mdm_tos_accepted", "value": false }, { "name": "common.ip_address", "value": "192.168.0.8" }, { "name": "android.media_card_capacity", "value": null }, { "name": "android.screenlock_pin_change_prompt", "value": "false" }, { "name": "common.mtd_anti_phishing_status", "value": "N/A" }, { "name": "common.client_build_date", "value": "2022-04-07T21:31:41.000Z" }, { "name": "android.security_patch_date", "value": "2022-06-05T00:00:00.000Z" }, { "name": "user.first_name", "value": null }, { "name": "common.intune_compliance_azure_device_compliance_status", "value": null }, { "name": "common.current_operator_name", "value": null }, { "name": "android.battery_zebra_base_cumulative_charge", "value": null }, { "name": "android.samsung_model_number", "value": null }, { "name": "android.device", "value": "oriole" }, { "name": "android.battery_zebra_serialnumber", "value": null }, { "name": "common.wifi_mac_address", "value": "6a:02:39:cb:58:13" }, { "name": "user.sam_account_name", "value": null }, { "name": "common.mtd_anti_phishing_vpn_status", "value": "N/A" }, { "name": "common.intune_compliance_azure_client_status_code", "value": "Not supported" }, { "name": "android.bulk_enrollment_profile", "value": null }, { "name": "common.intune_compliance_azure_device_report_time", "value": null }, { "name": "common.device_encrypted", "value": true }, { "name": "android.zebra_ota_capable", "value": false }, { "name": "android.dualdar_version", "value": null }, { "name": "android.security_patch", "value": "2022-06-05" }, { "name": "common.location", "value": null }, { "name": "android.battery_zebra_mfd", "value": null }, { "name": "common.memory_capacity", "value": 7775075696 }, { "name": "common.security_state", "value": "Ok" }, { "name": "common.intune_compliance_azure_device_id", "value": null }, { "name": "android.attestation", "value": "Unknown" }, { "name": "common.registration_uuid", "value": "7ca11b9157a5ac80" }, { "name": "common.appconnect_tos_accepted", "value": null }, { "name": "android.registration_status", "value": "Work Profile" }, { "name": "android.incremental", "value": "8650216" }, { "name": "android.dpm_encryption_status", "value": "ACTIVE PER USER" }, { "name": "common.model_name", "value": null }, { "name": "android.media_card_free", "value": null }, { "name": "android.zebra_system_update_information", "value": null }, { "name": "android.safety_net_enabled", "value": false }, { "name": "android.samsung_dm", "value": null }, { "name": "android.battery_zebra_usage_numb", "value": null }, { "name": "android.kiosk_enabled", "value": false }, { "name": "common.registration_date", "value": "2022-07-05T07:34:05.000Z" }, { "name": "android.Client_version_code", "value": 652 }, { "name": "android.secure_apps_enabled", "value": false }, { "name": "android.prv_password_expiration_timeout", "value": 0 }, { "name": "common.storage_capacity", "value": 128000000000 }, { "name": "android.security_reason", "value": "" }, { "name": "common.miclient_last_connected_at", "value": "2022-07-05T07:45:27.000Z" }, { "name": "android.gcmToken", "value": true }, { "name": "android.os_update_path", "value": null }, { "name": "android.knox_version", "value": "" }, { "name": "android.c2dmToken", "value": null }, { "name": "android.efota_capable", "value": false }, { "name": "common.storage_free", "value": 111821280000 }, { "name": "common.intune_compliance_azure_device_compliance_report_status", "value": null }, { "name": "android.battery_zebra_present_charge", "value": null }, { "name": "common.manufacturer", "value": "Google" }, { "name": "android.device_roaming_flag", "value": "Not Available" }, { "name": "common.roaming", "value": false }, { "name": "common.memory_free", "value": 3813408768 }, { "name": "common.model", "value": "Pixel 6" }, { "name": "android.watch_app_installed", "value": false }, { "name": "common.apns_capable", "value": false }, { "name": "android.wear_paired", "value": false }, { "name": "common.cellular_technology", "value": "none" }, { "name": "common.battery_level", "value": 95 }, { "name": "common.enrollment_id", "value": "DFIQ-TWHE-GHZ7-5MOIN-LL3P-AHPO-T" }, { "name": "common.auth_only", "value": false }, { "name": "android.device_up_time", "value": 18 }, { "name": "android.google_device_account", "value": false }, { "name": "common.SerialNumber", "value": null }, { "name": "common.appconnect_tos_accepted_date", "value": null }, { "name": "common.processor_architecture", "value": null }, { "name": "user.user_id", "value": "miadmin" } ], "totalCount": 143, "resultCount": 143 }

Get Embedded Identity Document (EID) details

This call gets the EID information for the built-in Subscriber Identity Modules/Subscriber Identification Modules (SIMs) of iOS 14 and later 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 Role

Category: Device Management

Role Description: View dashboard, device page, device details

HTTP method

GET

Request URI

/api/v2/devices/simdetails/{deviceId}?adminDeviceSpaceId={adminDeviceSpaceId}

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

adminDeviceSpaceId=1

deviceId

Required

Parameter Type: Path

Data Type: String

The deviceId is the device UUID.

dd8adade-4d26-4aad-96cc-0cc317692aeb

Response fields

 

Field

Description

results

Container for results.

        eid

The EID identifier.

        phoneNumber

The associated phone number.

        carrierSettingVersion

Version of the carrier settings software.

        carrierNetwork

The carrier, for example, Verizon.

        slot

Slot position of associated EID.

        simLabel

Label of EID.

totalCount

Total EID arrays returned.

resultCount

Total result records returned.

Sample request and response

Request

curl --location --request GET 'https://[Ivanti EPMM]/api/v2/devices/simdetails/dd8adade-4d26-4aad-96cc-0cc317692aeb?adminDeviceSpaceId=1' \

--header 'Accept: application/json, text/plain, */*' \

--header 'Content-Type: application/json' \

--header 'Authorization: Basic <token>' \

Response

{

    "results": [

        {

            "eid": "N/A",

            "phoneNumber": "N/A",

            "carrierSettingVersion": "N/A",

            "carrierNetwork": "N/A",

            "slot": "CTSubscriptionSlotOne",

            "simLabel": "N/A"

        },

        {

            "eid": "89049032005008882600048285696082",

            "phoneNumber": "+14089660949",

            "carrierSettingVersion": "41.7.70",

            "carrierNetwork": "Verizon ",

            "slot": "CTSubscriptionSlotTwo",

            "simLabel": "Secondary"

        }

    ],

    "totalCount": 2,

    "resultCount": 2

}

Get Last Sync Time and State of ActiveSync Devices

This call gets the sync time and state of ActiveSync devices. The CSV output of this call is a helpful reference for operators who retire devices from Ivanti EPMM and need to remove the same devices from the ActiveSync profile on Microsoft Exchange. For example, an admin could create PowerShell scripts to read the response of this call and delete devices from the ActiveSync profile on Microsoft Exchange that have not synced in a week.

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: Device Management

Role Description: Manage ActiveSync device

HTTP method

GET

Request URI

api/V2/activesync/devicereport?daysIdle=0&state=a

Request parameters

 

Parameter

Description

Sample Value

daysIdle

Required

Parameter Type: Query

Data Type: Integer

Enter a value corresponding the number of days idle devices should be to be returned by the call. For example, to find devices that have been idle for one day, use 1 (one). Use 0 (zero) to find devices regardless of the last session time.

0

state

Parameter Type: Query

Data Type: String

Valid values:

a
Searches for allowed devices

b
Searches for blocked devices

w
Searches for wiped devices

q
Searches for allowed quarantined devices

r
Searches for retired devices

 

For ease of use, the call accepts the entire word. For example, instead of "state=r", the call would accept "state=retired".

Note: except for retired, all values correspond to ActiveSyncStatus enumeration. "retired" corresponds to eas_device entries with the trash flag set to true.

a

Response fields

This call returns information about ActiveSync devices matching search criteria in the HTTP response body in CSV format. The first line is the CSV column header line, followed by the actual ActiceSync device data, one row per ActiveSync device.

 

Field

Description

DeviceId

ActiveSync Device ID

MailboxId

Mailbox ID

Status

This is the device status.

One of:

Registered

Unregistered

SyncStatus

ActiveSync status.

One of:

Allowed

Blocked

Wiped

Quarantined

Retired

One of:

true

false

LastSyncTime

Last session time, formatted in GMT. The format is always yyyy-MM-dd hh:mm:ss z.

SentryType

One of:

Standalone

Integrated

Sample request and response

Request

curl -X GET -H "Authorization: Basic <token>" https://[Ivanti EPMM]/api/v2/activesync/devicereport/?daysIdle=0&state=A

Response

DeviceId,MailboxId,Status,SyncStatus,Retired,LastSyncTime,SentryType

DeviceID-1,[email protected],Unregistered,Allowed,false,2015-03-30 03:14:57 GMT,Standalone

DeviceID-2,[email protected],Registered,Blocked,false,2015-03-31 03:14:57 GMT,Integrated

DeviceID-3,[email protected],Unregistered,Unknown,true,2015-04-01 03:14:57 GMT,Integrated

Get app control compliance information for a device

This call gets app control compliance information for a device.

Required Roles

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 dashboard, device page, device details

Category: Other Roles
Role Description: Mobile App

HTTP method

GET

Request URI

api/v2/devices/<deviceUuid>/appcompliance

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

deviceUuid

Required

Parameter Type: Path

Data Type: String

The device UUID.

7b3ad194-3bc0-4229-b30f-26f6bb277dd7

Response fields

 

Field

Description

results

Container for the results array shown below.

    deviceUuid

 

    appViolationsByType

 

        Disallowed

 

                type

 

                appName

 

                appVersion

 

        Required

 

                type

 

                appName

 

                appVersion

 

Sample request and response

Request

curl -k -sS -u <userName>:<password> -XGET 'https://[Ivanti EPMM]/api/v2/devices/7b3ad194-3bc0-4229-b30f-26f6bb277dd7/appcompliance?adminDeviceSpaceId=1'

Response

{

    "results": {

        "deviceUuid": "7b3ad194-3bc0-4229-b30f-26f6bb277dd7",

        "appViolationsByType": {

            "Disallowed": [

                {

                    "type": "Disallowed",

                    "appName": "Sudoku",

                    "appVersion": "4.6"

                }

            ],

            "Required": [

                {

                    "type": "Required",

                    "appName": "Evernote",

                    "appVersion": null

                },

                {

                    "type": "Required",

                    "appName": "Waze",

                    "appVersion": null

                }

            ]

        }

    }

}

Wake up a device

This call wakes up a device by requiring it to check in.

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: Device Management
Role Description: Force device check-in

HTTP method

PUT

Request URI

api/v2/devices/wakeup

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

deviceUuids

Required

Parameter Type: Request body

Data Type: String

The device UUIDs of the devices to wake up. Use commas to separate multiple values.

af0cea8b-f56c-49f5-b615-76cc34936b2f

note

Parameter Type: Request body

Data Type: String

Note clarifying the wake up/check-in request.

Please check in your device.

Response fields

 

Field

Description

actionType

Describes the action type, in this case, WAKEUP_DEVICE.

deviceResults

Indicates the outcome for the action per device.

successful

Indicates success, true or false.

Sample request and response

Request

curl --user <username>:<password> --header 'Content-Type: application/json' --request PUT 'https://[Ivanti EPMM]/api/v2/devices/wakeup?adminDeviceSpaceId=1' --data '{"deviceUuids": ["af0cea8b-f56c-49f5-b615-76cc34936b2f"], "note": "something"}'

Response

{

    "actionType": "WAKEUP_DEVICE",

    "deviceResults": {

        "af0cea8b-f56c-49f5-b615-76cc34936b2f": "com.mobileiron.vsp.messages.device.action.successful"

    },

    "successful": true

}

Send message

This call sends a message to devices with the specified deviceUuids.

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: Device Management
Role Description: Send message to device

HTTP method

PUT

Request URI

api/v2/devices/sendmessage

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

deviceUuids

Required

Parameter Type: Request body

Data Type: String

The device UUIDs of the devices to which to send the message. Use commas to separate multiple values.

30b8b722-2954-42ab-bda8-700facfa249a

note

Parameter Type: Request body

Data Type: String

Note clarifying the wake up/check-in request.

Alerting to data roaming expense.

additionalParameters

Parameter Type: Request body

Data Type: String

Container for message and mode parameters.

{

    "message": "Data roaming is expensive.",

    "mode": "email",

    "subject": "About data roaming"

}

message

Parameter Type: Request body

Data Type: String

Message to send to the specified devices.

Data roaming is expensive

mode

Parameter Type: Request body

Data Type: String

Mode of the message:

pns (push notifications)

sms

email (email takes the subject parameter, too)

email

subject

Parameter Type: Request body

Data Type: String

Provide if desired when the message mode is email.

About data roaming

Response fields

 

Field

Description

results

Container for the results.

    resultId

ID of the result.

    resultMessage

Message associated with the resultID.

    records

List of affected device UUIDs.

resultCount

Count of affected devices.

actionType

Describes the action type, in this case, SEND_MESSAGE.

deviceResults

Indicates success or failure for each device.

successful

Indicates success, true or false.

Sample request and response

Request

curl --user <username>:<password> --header 'Content-Type: application/json' --request PUT 'https://[Ivanti EPMM]/api/v2/devices/sendmessage?adminDeviceSpaceId=1' --data '{"deviceUuids": ["30b8b722-2954-42ab-bda8-700facfa249a"], "note": "Alerting to data roaming expense.", "additionalParameters": {"message" : "Data roaming is expensive.", "mode": "email", "subject" : "About data roaming”} }'

Response

{

    "results": [

        {

            "resultId": "114",

            "resultMessage": null,

            "records": [

                "30b8b722-2954-42ab-bda8-700facfa249a"

            ]

        }

    ],

    "resultCount": 1,

    "actionType": "SEND_MESSAGE",

    "deviceResults": {

        "30b8b722-2954-42ab-bda8-700facfa249a": "com.mobileiron.vsp.messages.device.action.successful"

    },

    "successful": true

}

Apply labels to devices

This call applies labels to 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 Role

Category: Device Management
Role Description: Apply and remove device label

HTTP method

PUT

Request URI

api/v2/devices/labels/label1,label2/add

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

label1,label2

Required

Parameter Type: Query

Data Type: String

Labels to apply to the devices.

ios,company-owned

deviceUuids

Required

Parameter Type: Request body

Data Type: String

The device UUIDs of the devices to which to apply the labels. Use commas to separate multiple values.

9a56d1e5-ca74-4776-868c-389c849348b2

Response fields

 

Field

Description

results

Container for the results.

    resultId

ID of the result.

    resultMessage

Message associated with the resultID.

    records

An array of values for each label applied:

uuid

id

principal

deviceSpaceId

deviceSpacePath

label

device

resultCount

Count of affected devices.

actionType

Describes the action type, in this case, APPLY_LABEL_TO_DEVICES".

deviceResults

Contain failure reasons, for example "Device not found," or "Invalid request. Label not found for Label with ID".

The successful records can be found in "records" section.

successful

Indicates success, true or false.

Sample request and response

Request

ccurl  --user <username>:<password> --header 'Content-Type: application/json' --request PUT 'https://[Ivanti EPMM]/api/v2/devices/labels/ios,company-owned/add?adminDeviceSpaceId=1' --data '{"deviceUuids": ["af0cea8b-f56c-49f5-b615-76cc34936b2f"]}'

Response

{

    "results": [

        {

            "resultId": "114",

            "resultMessage": null,

            "records": [

                {

                    "uuid": null,

                    "id": null,

                    "principal": null,

                    "deviceSpaceId": 1,

                    "deviceSpacePath": "/1/",

                    "label": "ios",

                    "device": [

                        {

                            "uuid": "9a56d1e5-ca74-4776-868c-389c849348b2"

                        }

                    ]

                },

                {

                    "uuid": null,

                    "id": null,

                    "principal": null,

                    "deviceSpaceId": 1,

                    "deviceSpacePath": "/1/",

                    "label": "company-owned",

                    "device": [

                        {

                            "uuid": "9a56d1e5-ca74-4776-868c-389c849348b2"

                        }

                    ]

                }

            ]

        }

    ],

    "resultCount": 1,

    "actionType": "APPLY_LABEL_TO_DEVICES",

    "deviceResults": { },

    "successful": true

}

Remove labels from devices

This call removes labels from 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 Role

Category: Device Management
Role Description: Apply and remove device label

HTTP method

PUT

Request URI

api/v2/devices/labels/label1,label2/remove

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

label1,label2

Required

Parameter Type: Query

Data Type: String

Labels to remove from the devices.

ios,company-owned

deviceUuids

Required

Parameter Type: Request body

Data Type: String

The device UUIDs of the devices from which to remove the labels. Use commas to separate multiple values.

af0cea8b-f56c-49f5-b615-76cc34936b2f

Response fields

 

Field

Description

results

Container for the results.

    resultId

ID of the result.

    resultMessage

Message associated with the resultID.

    records

An array of values for each label applied:

uuid

id

principal

deviceSpaceId

deviceSpacePath

label

device

resultCount

Count of affected devices.

actionType

Describes the action type, in this case, REMOVE_LABEL_FROM_DEVICES.

deviceResults

Indicates success or failure for each device.

successful

Indicates success, true or false.

Sample request and response

Request

curl --user <username>:<password> --header 'Content-Type: application/json' --request PUT 'https://[Ivanti EPMM]/api/v2/devices/labels/ios,company-owned/remove?adminDeviceSpaceId=1' --data '{"deviceUuids": ["af0cea8b-f56c-49f5-b615-76cc34936b2f"]}'

Response

{

    "results": [

        {

            "resultId": "114",

            "resultMessage": null,

            "records": [

                {

                    "uuid": null,

                    "id": null,

                    "principal": null,

                    "deviceSpaceId": 1,

                    "deviceSpacePath": "/1/",

                    "label": "ios",

                    "device": [

                        {

                            "uuid": "9a56d1e5-ca74-4776-868c-389c849348b2"

                        }

                    ]

                },

                {

                    "uuid": null,

                    "id": null,

                    "principal": null,

                    "deviceSpaceId": 1,

                    "deviceSpacePath": "/1/",

                    "label": "company-owned",

                    "device": [

                        {

                            "uuid": "9a56d1e5-ca74-4776-868c-389c849348b2"

                        }

                    ]

                }

            ]

        }

    ],

    "resultCount": 1,

    "actionType": "REMOVE_LABEL_FROM_DEVICES",

    "deviceResults": { },

    "successful": true

}

Wipe devices

This call wipes 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 Role

Category: Device Management
Role Description: Wipe device

HTTP method

PUT

Request URI

api/v2/devices/wipe

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

deviceUuids

Required

Parameter Type: Request body

Data Type: String

The device UUIDs of the devices to wipe.

{
    "deviceUuids": [
        "cb1bcc55-bba3-41df-9efa-a3496b065bf9"
    ], 
     
    "additionalParameters": {
        "preserveDataPlan": "true"
     "sendWipeNotification": "false"
    }
}

note

Parameter Type: Request body

Data Type: String

Note clarifying the wipe request.

additionalParameters

Parameter Type: Request body

Data Type: String

Container for additional parameters. Currently, the additional supported parameter is:

preserveDataPlan

If true, preserves the data plan upon wiping the device.

Valid values:

  • true

  • false

Response fields

Field

Description

results

Container for results.

        resultId

ID of the result.

        resultMessage

Message for the result.

        records

List of devices affected.

resultCount

Count of devices affected.

actionType

Describes the action type, in this case, WIPE.

deviceResults

Indicates the outcome for the action per device.

successful

Indicates success, true or false.

Sample request and response

Request

curl --location --request PUT 'https://[Ivanti EPMM]/api/v2/devices/wipe?adminDeviceSpaceId=1' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic <token>' \ --data '{"deviceUuids": ["cb1bcc55-bba3-41df-9efa-a3496b065bf9"], "note": "Employee left company.", "additionalParameters": {"preserveDataPlan": "true"}}'

Response

{ "results": [ { "resultId": "114", "resultMessage": null, "records": [ "cb1bcc55-bba3-41df-9efa-a3496b065bf9" ] } ], "resultCount": 1, "actionType": "WIPE", "deviceResults": { "cb1bcc55-bba3-41df-9efa-a3496b065bf9": "com.mobileiron.vsp.messages.device.action.successful" }, "successful": true }

Lock devices

This call locks 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 Role

Category: Device Management
Role Description: Lock & unlock device

HTTP method

PUT

Request URI

api/v2/devices/lock

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

deviceUuids

Required

Parameter Type: Request body

Data Type: String

The device UUIDs of the devices to lock.

af0cea8b-f56c-49f5-b615-76cc34936b2f

note

Parameter Type: Request body

Data Type: String

Note clarifying the lock request.

Employee left company.

Response fields

 

Field

Description

actionType

Describes the action type, in this case, LOCK.

deviceResults

Indicates the outcome for the action per device.

successful

Indicates success, true or false.

Sample request and response

Request

curl --user <username>:<password> --header 'Content-Type: application/json' --request PUT 'https://[Ivanti EPMM]/api/v2/devices/lock?adminDeviceSpaceId=1' --data '{"deviceUuids": ["af0cea8b-f56c-49f5-b615-76cc34936b2f"], "note": "Employee left company."}'

Response

{

    "actionType": "LOCK",

    "deviceResults": {

        "af0cea8b-f56c-49f5-b615-76cc34936b2f": "com.mobileiron.vsp.messages.device.action.successful"

    },

    "successful": true

}

Unock devices

This call unlocks 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 Role

Category: Device Management
Role Description: Lock & unlock device

HTTP method

PUT

Request URI

api/v2/devices/unlock

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

deviceUuids

Required

Parameter Type: Request body

Data Type: String

The device UUIDs of the devices to unlock.

af0cea8b-f56c-49f5-b615-76cc34936b2f

note

Parameter Type: Request body

Data Type: String

Note clarifying the unlock request.

Virus scan successful.

Response fields

 

Field

Description

actionType

Describes the action type, in this case, UNLOCK.

deviceResults

Indicates the outcome for the action per device.

successful

Indicates success, true or false.

Sample request and response

Request

curl --user <username>:<password> --header 'Content-Type: application/json' --request PUT 'https://[Ivanti EPMM]/api/v2/devices/unlock?adminDeviceSpaceId=1' --data '{"deviceUuids": ["af0cea8b-f56c-49f5-b615-76cc34936b2f"], "note": "Virus scan successful."}'

Response

{

    "actionType": "UNLOCK",

    "deviceResults": {

        "af0cea8b-f56c-49f5-b615-76cc34936b2f": "com.mobileiron.vsp.messages.device.action.successful"

    },

    "successful": true

}

Retire devices

This call retires 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 Role

Category: Device Management
Role Description: Retire device

HTTP method

PUT

Request URI

api/v2/devices/retire

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

deviceUuids

Required

Parameter Type: Request body

Data Type: String

The device UUIDs of the devices to retire.

"e4dd5f15-0349-49a9-9cc7-0e6d121ff229","7f2f9390-4593-4351-b065-6409016026be"

note

Parameter Type: Request body

Data Type: String

Note clarifying the retire request.

New phone issued.

additionalParameters: isActionForced:true|false

Parameter Type: Request body

Data Type: Boolean

Used to force retirement of devices in the RETIRE PENDING state. To force retirement, use true.

"additionalParameters":{"isActionForced":true}

Response fields

 

Field

Description

actionType

Describes the action type, in this case, RETIRE.

deviceResults

Indicates the outcome for the action per device.

successful

Indicates success, true or false.

Sample request and response

Request

curl --user miadmin:<password> --header 'Content-Type: application/json' --request PUT 'https://[Ivanti EPMM]/api/v2/devices/retire?adminDeviceSpaceId=1' --data '{"deviceUuids": ["e4dd5f15-0349-49a9-9cc7-0e6d121ff229","7f2f9390-4593-4351-b065-6409016026be"], "note": "New phone issued", "additionalParameters":{"isActionForced":true}}'

Response

{ "results": [ { "resultId": "114", "resultMessage": null, "records": [ "754ee0ba-a2f3-4f45-814e-fcfe230665f7" ] } ], "resultCount": 1, "actionType": "RETIRE", "deviceResults": { "754ee0ba-a2f3-4f45-814e-fcfe230665f7": "com.mobileiron.vsp.messages.device.action.successful" }, "successful": true }

Open TeamViewer session

This call opens a TeamViewer session for an Android or iOS device. The support engineer opens the supporter link in the return in a browser to initiate the Remote Display session.

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: Device Management
Role Description: Manage devices

HTTP method

POST

Request URI

msa/v2/remote/[create_teamviewer_session_android|create_teamviewer_session_ios]

Request parameters

 

Parameter

Description

Sample Value

create_teamviewer_session_android

or

create_teamviewer_session_ios

Required. One of the following is required:

create_teamviewer_session_android

create_teamviewer_session_ios

Parameter Type: Path

Data Type: String

The type of device for which to create the TeamViewer session.

create_teamviewer_session_android

adminDeviceSpaceId

Required

Parameter Type: Request body

Data Type: Number

Device space ID of the administrator.

1

deviceUuid

Required

Parameter Type: Request body

Data Type: String

The device UUID of the device for which to open a TeamViewer session.

af0cea8b-f56c-49f5-b615-76cc34936b2f

Response fields

 

Field

Description

results

    httpStatus
    error
    error_description
    error_code
    error_signature
    code
    state
    groupid
    end_customer
    description
    assigned_userid
    end_customer_link
    supporter_link This is the link the support engineer opens in a browser to initiate the Remote Display session.
    valid_until
messages
        type
        messageKey
        localizedMessage

Sample requests and response

Requests

Android

curl -v -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Basic <token>" -X POST https://[Ivanti EPMM]/msa/v2/remote/create_teamviewer_session_android -d "adminDeviceSpaceId=1&deviceUUID=2493c9a5-a9c8-43cb-af4c-9475dac8ba69"

iOS

curl -v -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Basic <token>" -X POST https://[Ivanti EPMM]/msa/v2/remote/create_teamviewer_session_ios -d "adminDeviceSpaceId=1&deviceUUID=8af2f758-15c4-4394-ac67-3729e3dfe2d0"

Response

{

    "results": {

        "httpStatus": "OK",

        "error": null,

        "error_description": null,

        "error_code": null,

        "error_signature": null,

        "code": "s35-924-946",

        "state": "Open",

        "groupid": "g86972161",

        "end_customer": null,

        "description": null,

        "assigned_userid": "u75347768",

        "end_customer_link": "https://get.teamviewer.com/s35924946",

        "supporter_link": "[https://get.teamviewer.com/s35924946-9c0G78d8rMMZ]",

        "valid_until": "2019-04-10T01:46:06Z"

    },

    "messages": [

        {

            "type": "Info",

            "messageKey": "com.mobileiron.vsp.messages.teamviewer.create.session",

            "localizedMessage": "Created TeamViewer session code"

        }

    ]

}

Check device compliance

This call checks device compliance for selected or all 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 Role

Category: Device Management
Role Description: Manage devices

or

Category: Policy Management
Role Description: Manage compliance action

HTTP method

PUT

Request URI

api/v2/devices/checkcompliance

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

allDevices

Required

Parameter Type: Query

Data Type: Boolean

Specifies whether to return compliance information for all devices, or only for the devices indicated in the request body.

Valid values:

true

false

If true, then you must send {} in the request body as raw JSON (application/json) text. If false, then you must send a list of deviceUuids in the request body. See the Requests.

true

deviceUuids

Parameter Type: Request body

Data Type: String

The device UUIDs of the devices for which to check device compliance.

If the value of the allDevices parameter is true, then send {} in the request body as raw JSON (application/json) text.

If the value of the allDevices parameter is false, then send the list of device UUIDs in the request body as raw JSON (application/json) text, like this, for example:

{

    "deviceUuids": [

        "ca7e632e-1c64-4ef3-8ed4-92480cb30a6f"

    ]

}

See the Requests.

{"deviceUuids": ["ca7e632e-1c64-4ef3-8ed4-92480cb30a6f"]}

Response fields

 

Field

Description

results

 

        resultId

 

        resultMessage

 

        records

 

resultCount

 

actionType

CHECK_COMPLIANCE

deviceResults

 

successful

true or false.

Sample requests and response

Requests

Check Compliance for specific devices

curl --user <username>:<password> --header 'Content-Type: application/json' --request PUT 'https://[Ivanti EPMM]/api/v2/devices/checkcompliance?adminDeviceSpaceId=1&allDevices=false' --data '{"deviceUuids": ["af0cea8b-f56c-49f5-b615-76cc34936b2f"]}'

Check Compliance for all devices

curl --user <username>:<password> --header 'Content-Type: application/json' --request PUT 'https://[Ivanti EPMM]/api/v2/devices/checkcompliance?adminDeviceSpaceId=1&allDevices=true' --data '{}'

Response

{

    "results": [

        {

            "resultId": "114",

            "resultMessage": null,

            "records": [

                "af0cea8b-f56c-49f5-b615-76cc34936b2f"

            ]

        }

    ],

    "resultCount": 1,

    "actionType": "CHECK_COMPLIANCE",

    "deviceResults": {},

    "successful": true

}

Get device compliance and reason for non compliance

This call checks device compliance for the device specified with the deviceUuid parameter, and returns reasons for non-compliance, if present.

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: Device Management
Role Description: Manage devices

HTTP method

GET

Request URI

/api/v2/devices/{deviceUuid}/rulecompliance

Request parameters

 

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

deviceUuid

Parameter Type: Path

Data Type: String

The UUID of the devices for which to get compliance status and non-compliance reasons.

9c311225-a7e1-486b-8682-96f96bfb38be

Response fields

 

Field

Description

results

        id
        deviceUuid
        ruleId
        complianceAction
        quarantineAction
        createdAt
        userDisplayName
        userId
        platformName
        model
        actionName
        ruleName
        complianceActionNames
totalCount
resultCount

Sample request

curl -X GET -u <username>:<password> -H 'Content-Type: application/json' 'https://[Ivanti EPMM]/api/v2/devices/9c311225-a7e1-486b-8682-96f96bfb38be/rulecompliance?adminDeviceSpaceId=1'

Sample response

{

    "results": [

        {

            "id": 1,

            "deviceUuid": "9c311225-a7e1-486b-8682-96f96bfb38be",

            "ruleId": 1,

            "complianceAction": 1,

            "quarantineAction": 0,

            "createdAt": 1558738202000,

            "userDisplayName": "miadmin",

            "userId": "miadmin",

            "platformName": "iOS 11.2",

            "model": "iPhone 6s",

            "actionName": "Send Alert",

            "ruleName": "test2",

            "complianceActionNames": [

                "ALERT"

            ]

        }

    ],

    "totalCount": 1,

    "resultCount": 1

}