General Guidelines and Conventions

The HTTP requests use two types of parameters:

Path parameters continue the URI path using a slash (/) for a separator. For example, to get details for a device, you specify its device uuid with a path parameter. The following shows the URI format for this request, and an example:

https:///api/v1/dm/devices/

https://<Ivanti EPMM>/api/v1/dm/devices/4239b999-46e3-423b-b808-54fff69b544c

If a request uses path parameters, they are specified in the URI format for the request.

Query parameters are included in the URI path using a question mark or ampersand (? or &). For example, to retire a device, after specifying the device uuid as a path parameter, you specify a reason as a query parameter. The following shows the URI format for this request, and an example:

https:///api/v1/dm/devices/retire/

https://<Ivanti EPMM>/api/v1/dm/devices/retire/c097c9e2-c82e-40f6-9e69-a0478c4fcee0?reason=AnyReasonTextYouChoose

The first query parameter is preceded by a question mark (?), using the following format:

?parameterName=parameterValue

Subsequent query parameters are preceded by an ampersand (&), using the following format:

&parameterName=parameterValue

For example, to get all the Android devices that have a particular application installed, use the following request:

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=Frog%20Toss!_017%201.0&platform=A

Note: If a parameter is not shown in a request’s URI format with a slash, it is a query parameter; the URI format for a request shows only the path parameters. The description that follows each URI format provides information on the query parameters, if any.

Many API calls include start and end dates in the request.  In general, the dates are optional.  If dates are not included, all available records will be returned.  If start and end dates are included in the request, only records within the date range will be returned.

Dates can be in the following formats

Many API calls require a phone number in the request.  The following rules apply to an input phone number:

Depending on the HTTP request, use one of the following HTTP request methods:

Each request description specifies which HTTP request method to use.

Requests to the API can return xml or json, based on the request headers.

Responses from the API use the codes listed below.  In addition, a “Success” message is shown for successful method executions.  When method executions fail, a descriptive error message is displayed.

Some requests result in responses that contain many records. For example, the request for the list of all devices on which a specific application is installed can match hundreds or thousands of devices.

To return more than the first 100 records, these APIs support the limit and offset query parameters. These parameters allow you to get successive sets of records in successive responses.

Specifically, use these query parameters to do the following:

For example, the following request returns the first 50 devices that have the LinkedIn app installed:

The value is zero-based. For example, the following request returns 50 devices, starting with the 101^(st) device:

The offset parameter defaults to 0. Therefore, both of the following requests return 50 devices, starting with the first device:

Therefore, to get successive sets of records in successive responses, increase the offset value by the limit value in each request. For example:

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=50&offset=0

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=50&offset=50

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=50&offset=100

For the API that gets the devices that have a particular app installed (Get Devices by Application Name), you can also set limit to -1 to get all the devices in one response. For example:

https://<Ivanti EPMM>/api/v1/apps/inventory/app?appname=LinkedIn&limit=-1

The following table summarizes the limit and offset query parameters.

The requests and responses use identifiers for devices and users.

Every time a user or a device is created, Ivanti EPMM internally generates a unique identifier, called a “uuid”.  Each device gets a unique uuid. Because a single user can have multiple devices, each user gets a unique uuid, independent of any devices used. 

Other IDs are used for other purposes, such as identifying a network, and are described in the APIs.

Refer to the Administrator’s Guide for an up-to-date matrix which displays supported features by operating system and platform.  If a particular feature is not supported by an OS, the feature API will not return a valid response.

FireFox and Chrome are the supported browsers. Internet Explorer is not supported. Plugins like Poster for FireFox and Advanced REST Client for Chrome are recommended for interacting with the http server; simply submitting a URI in the browser does not consistently result in a properly rendered response.

All the requests are wrapped in WebServiceRequest, and the responses are wrapped in WebServiceResponse.  startDate and endDate from the request are returned in the response.