Please enable JS

REST API

ezmdm™ REST API

ezmdm™ provides a powerful REST API to enable you to integrate EzMDM into your IT environement. Using this API, you can retrieve, add and update groups and users. You can also utilize the API to retrieve a list of devices and trigger push notifications to those devices. Please see the following documentation for instructions on how to call the API.

Authorization

Each REST API is authorized by the API Key included in the url. The user who created you EzMDM account is your account administrator. The account administrator can request an API key from the account options menu that is presented when you click your username in the upper, right corner of EzMDM. You should keep this key secure as it provides access to your EzMDM account. If you believe the current key has become compromised, you can request a new API Key which will disable the previous key.

API Methods

The following HTTPs methods are utilized by the API

  • GET - retrieves a list or single item
  • PUT - adds a new item
  • POST - updates an item. The item's identifier must be included in the URL.

URL Format

The URL is comprised of the following components:

  • The base URL of /api/v1
  • The API key
  • The name of the item, e.g. device
  • In some cases, the identifier of a specific item

Each component is separated by a forward slash to comprise the complete URL. The URL is not case sensitive so either deviceLoation, DeviceLocation and devicelocation coudl be utilized. There are examples of every URL below.

Items

The following items can be retrieved and/or managed via the API:

  • Group
  • User
  • Device
  • DeviceLocation

The fields specific to each of these can be found towards the bottom of this page.

PUT and POST Data

When adding or updating an item you will need to send additional data. This data should be in the normal post format as if submitted from an html form. When performing an update, you need only send the fields and values you wish to change. For example, if you wished to change the name associated with a device, you could simply send the following:
name=Bob's iPhone&

Item Identifiers

Each item has a unique identifier. You will utilize these identifiers when updating an item via a POST. You may utilize an identifier with a GET if you wish to retrieve only information about a specific item. For example, if you only wish to retrieve the current information about a single device. You can also use an identifier when retrieving a list. For example, if you wish to retrieve DeviceLocation records related to a specific device you would append the device identifier to the URL. In fact, the DeviceLocation request is an example of a request whereby you must provide an identifier.

Response Data

The data returned from an API call will be JSON. The JSON will have the following properties:

  • success: true or false
  • error: if success is false, the reason for the failure
  • data: depends on the method called -- see examples
    GET: the item or list retrieved
    PUT: the identifier of the added item
    POST: this property is not present in the response
  • page: the set of items -- see Paging below
  • total: the total number of items that can be retrieved with this URL

Paging

When a list of records is requested, a maximum of 100 items will be returned. If you wish to retrieve less than 100 items, you can specify the number by adding a limit value in the URL query string -- see the URL examples below. You can also provide a page value to retrieve the next set of items. The first page is page 1.

Response Data Examples

// retrieve a list of items
{
  "success": true,
  "data": [
     ... one or more objects
  ],
  "page": 1,
  "total": 53
}

// retrieve a single item
{
  "success": true,
  "data": {
     ... the object properties
  }
}

// add an item
{
  "success": true,
  "data": "123456789012345678901234567890"
}

// error response
{
  "success": false,
  "error": "Invalid API Key"
}

URL Examples

The following list shows examples of URLs that could be utilized with the API.

You would replace API_KEY and ITEM_ID with your actual API Key and the appropriate ITEM_ID

  • Retrieve the list of groups
    GET https://www.ezmdm.com/api/v1/API_KEY/group
  • Add a new group
    PUT https://www.ezmdm.com/api/v1/API_KEY/group
  • Update a group
    POST https://www.ezmdm.com/api/v1/API_KEY/group/ITEM_ID
  • Retrieve the list of users
    GET https://www.ezmdm.com/api/v1/API_KEY/user
  • Retrieve the list of users for a specific group
    GET https://www.ezmdm.com/api/v1/API_KEY/user/ITEM_ID (Note: the item identifier is a group identifier)
  • Add a new user
    PUT https://www.ezmdm.com/api/v1/API_KEY/user
  • Update a user
    POST https://www.ezmdm.com/api/v1/API_KEY/user/ITEM_ID
  • Retrieve the list of devices
    GET https://www.ezmdm.com/api/v1/API_KEY/device
  • Retrieve the list of devices, but only 10 and the second group of 10
    GET https://www.ezmdm.com/api/v1/API_KEY/device?limit=10&page=2&
  • Retrieve the list of devices for a specific user
    GET https://www.ezmdm.com/api/v1/API_KEY/device/ITEM_ID (Note: the item identifier is a user identifier)
  • Retrieve the list of device locations for a specific device
    GET https://www.ezmdm.com/api/v1/API_KEY/devicelocation/ITEM_ID (Note: the item identifier is a device identifier)