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"
}