NAV Navbar
Logo
API version 1.16

Introduction

The SimpleMDM API exists as a RESTful JSON implementation. It is designed to work over authenticated, HTTPS secured channels. This reference describes the extent of the API functionality available to you.

Since the API is based upon the HTTP protocol, you can directly interact with it using any HTTP client library.

Authentication

# To authenticate with curl, use the "-u" flag with each request. Be sure to include a trailing ":"

curl https://a.simplemdm.com/api/v1/account \
  -u {API_KEY}:

You authenticate with the SimpleMDM API by providing your secret API key with each request. The API uses HTTP Basic Authentication to receive your API key. It will look for your API key in the username field. The password field should be left blank.

You can retrieve your API key by signing into your SimpleMDM account, visiting “Settings” and then selecting the “API” tab.

Errors

Example response body

{
    "errors": [
        {
            "title": "object not found"
        }
    ]
}

When the API encounters an error with your request, it will respond with an HTTP status code and a JSON-formatted body with additional details.

Pagination

curl https://a.simplemdm.com/api/v1/apps?limit=3&starting_after=33 \
  -u {API_KEY}:

{
  "data": [
    {
      "type": "app",
      "id": 34,
      "attributes": {
        "name": "Afterlight",
        "bundle_identifier": "com.simonfilip.AfterGlow",
        "app_type": "app store",
        "itunes_store_id": 573116090
      }
    },
    {
      "type": "app",
      "id": 63,
      "attributes": {
        "name": "Surf Report",
        "bundle_identifier": "com.portlandsurfclub.ent.surfreport2.2",
        "app_type": "enterprise",
        "version": "2.2"
      }
    },
    {
      "type": "app",
      "id": 67,
      "attributes": {
        "name": "Scanner Pro",
        "app_type": "custom b2b",
        "itunes_store_id": 44827291
      }
    }
  ],
  "has_more": true
}

Many of the “list” API methods utilize cursor-based pagination using the limit and starting_after parameters.

Request

Argument Description
limit Optional. A limit on the number of objects to be returned, between 1 and 100. Defaults to 10.
starting_after Optional. A cursor in the form of an object ID. It is typically set to the id of the last object of the previous response. If unspecified, the API will start at the beginning of the object list.

Response

The response from the API will indicate whether additional objects are available with the has_more key.

Argument Description
has_more A boolean true or false, based on if additional records exist beyond the specified cursor and limit.

Account

Show

curl https://a.simplemdm.com/api/v1/account \
  -u {API_KEY}:

{
  "data": {
      "type": "account",
      "attributes": {
          "name": "SimpleMDM",
          "apple_store_country_code": "US"
      }
  }
}

Retrieve information about your account.

HTTP Request

GET https://a.simplemdm.com/api/v1/account

Update

curl https://a.simplemdm.com/api/v1/account \
  -F _method=PATCH \
  -d apple_store_country_code=AU \
  -u {API_KEY}:

{
  "data": {
      "type": "account",
      "attributes": {
          "name": "SimpleMDM",
          "apple_store_country_code": "AU"
      }
  }
}
Argument Description
name The name of the account.
apple_store_country_code The app store country that SimpleMDM uses for the account.

HTTP Request

PATCH https://a.simplemdm.com/api/v1/account

Apps

An app represents an app in your app catalog. You can manage your app catalog via the API and use assignment groups to install apps to your devices.

List all

curl https://a.simplemdm.com/api/v1/apps \
  -u {API_KEY}:

{
  "data": [
    {
      "type": "app",
      "id": 34,
      "attributes": {
        "name": "Afterlight",
        "bundle_identifier": "com.simonfilip.AfterGlow",
        "app_type": "app store",
        "itunes_store_id": 573116090
      }
    },
    {
      "type": "app",
      "id": 63,
      "attributes": {
        "name": "Surf Report",
        "bundle_identifier": "com.portlandsurfclub.ent.surfreport2.2",
        "app_type": "enterprise",
        "version": "2.2"
      }
    },
    {
      "type": "app",
      "id": 67,
      "attributes": {
        "name": "Scanner Pro",
        "app_type": "custom b2b",
        "itunes_store_id": 44827291
      }
    }
  ],
  "has_more": false
}

HTTP Request

GET https://a.simplemdm.com/api/v1/apps

Retrieve one

curl https://a.simplemdm.com/api/v1/apps/34 \
  -u {API_KEY}:

{
  "data": {
    "type": "app",
    "id": 34,
    "attributes": {
      "name": "Afterlight",
      "bundle_identifier": "com.simonfilip.AfterGlow",
      "app_type": "app store",
      "itunes_store_id": 573116090
    }
  }
}

HTTP Request

GET https://a.simplemdm.com/api/v1/apps/{APP_ID}

Create

curl https://a.simplemdm.com/api/v1/apps \
  -F binary=@SurfReport.ipa \
  -u {API_KEY}:

{
  "data": {
    "type": "app",
    "id": 63,
    "attributes": {
      "name": "Surf Report",
      "app_type": "enterprise",
      "version": "2.2",
      "bundle_identifier": "com.portlandsurfclub.ent.surfreport2.2"
    }
  }
}

You can use this method to add an App Store app, upload an enterprise iOS app, or upload macOS package to your app catalog.

HTTP Request

POST https://a.simplemdm.com/api/v1/apps

One and only one of of app_store_id, bundle_id, or binary must be specified. Name can optionally be specified if binary is specified.

Argument Description
app_store_id The Apple App Store ID of the app to be added. Example: 1090161858.
bundle_id The bundle identifier of the Apple App Store app to be added. Example: com.myCompany.MyApp1
binary The binary file with an ipa or pkg extension. File should be provided as multipart/form-data.
name The name that SimpleMDM will use to reference this app. If left blank, SimpleMDM will automatically set this to the app name specified by the binary.

Update

curl https://a.simplemdm.com/api/v1/apps/63 \
  -F binary=@SurfReportUpdated.ipa \
  -F _method=PATCH \
  -u {API_KEY}:

{
  "data": {
    "type": "app",
    "id": 63,
    "attributes": {
      "name": "Surf Report (Updated)",
      "app_type": "enterprise",
      "version": "2.3",
      "bundle_identifier": "com.portlandsurfclub.ent.surfreport2.3"
    }
  }
}

You can use this method to update the binary of an existing app.

HTTP Request

PATCH https://a.simplemdm.com/api/v1/apps/{APP_ID}

Argument Description
binary The binary file with an ipa or pkg extension. File should be provided as multipart/form-data.
name The name that SimpleMDM will use to reference this app. If left blank, SimpleMDM will automatically set this to the app name specified by the binary.

Delete

curl https://a.simplemdm.com/api/v1/apps/63 \
  -u {API_KEY}: \
  -X DELETE

HTTP/1.1 204 No Content

HTTP Request

DELETE https://a.simplemdm.com/api/v1/apps/{APP_ID}

Assignment Groups

An assignment group is an object that pairs apps with device groups and devices for the purpose of pushing apps and media to devices.

List all

curl https://a.simplemdm.com/api/v1/assignment_groups \
  -u {API_KEY}:

{
  "data": [
    {
      "type": "assignment_group",
      "id": 26,
      "attributes": {
        "name": "SimpleMDM",
        "auto_deploy": true
      },
      "relationships": {
        "apps": {
          "data": [
            {
              "type": "app",
              "id": 49
            }
          ]
        },
        "device_groups": {
          "data": [
            {
              "type": "device_group",
              "id": 37
            }
          ]
        },
        "devices": {
          "data": [
            {
              "type": "device",
              "id": 56
            }
          ]
        }
      }
    },
    {
      "type": "assignment_group",
      "id": 38,
      "attributes": {
        "name": "Productivity Apps",
        "auto_deploy": false
      },
      "relationships": {
        "apps": {
          "data": [
            {
              "type": "app",
              "id": 63
            },
            {
              "type": "app",
              "id": 67
            }
          ]
        },
        "device_groups": {
          "data": [
            {
              "type": "device_group",
              "id": 37
            },
            {
              "type": "device_group",
              "id": 38
            }
          ]
        },
        "devices": {
          "data": [
            {
              "type": "device",
              "id": 54
            }
          ]
        }
      }
    },

    ...

  ],
  "has_more": false
}

HTTP Request

GET https://a.simplemdm.com/api/v1/assignment_groups

Retrieve one

curl https://a.simplemdm.com/api/v1/assignment_groups/26 \
  -u {API_KEY}:

{
  "data": {
    "type": "assignment_group",
    "id": 26,
    "attributes": {
      "name": "SimpleMDM",
      "auto_deploy": true
    },
    "relationships": {
      "apps": {
        "data": [
          {
            "type": "app",
            "id": 49
          },
          {
            "type": "app",
            "id": 67
          }
        ]
      },
      "device_groups": {
        "data": [
          {
            "type": "device_group",
            "id": 37
          },
          {
            "type": "device_group",
            "id": 38
          }
        ]
      },
      "devices": {
        "data": [
          {
            "type": "device",
            "id": 54
          }
        ]
      }
    }
  }
}

HTTP Request

GET https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}

Create

curl https://a.simplemdm.com/api/v1/assignment_groups \
  -d name="Communication Apps"
  -u {API_KEY}: \
  -X POST

{
  "data": {
    "type": "assignment_group",
    "id": 43,
    "attributes": {
      "name": "Communication Apps",
      "auto_deploy": true
    },
    "relationships": {
      "apps": {
        "data": []
      },
      "device_groups": {
        "data": []
      },
      "devices": {
        "data": []
      }
    }
  }
}

HTTP Request

POST https://a.simplemdm.com/api/v1/assignment_groups

Argument Description
name The name of the assignment group.
auto_deploy Optional. Whether the apps should be automatically pushed to devices when they join any of the related device groups. Defaults to true.

Update

curl https://a.simplemdm.com/api/v1/assignment_groups/43 \
  -d auto_deploy=false
  -u {API_KEY}: \
  --request PATCH

HTTP/1.1 204 No Content

HTTP Request

PATCH https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}

Argument Description
name The name of the assignment group.
auto_deploy Optional. Whether the apps should be automatically pushed to devices when they join any of the related device groups. Defaults to true.

Delete

curl https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID} \
  -u {API_KEY}: \
  -X DELETE

HTTP/1.1 204 No Content

HTTP Request

DELETE https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}

Assign app

curl https://a.simplemdm.com/api/v1/assignment_groups/43/apps/21 \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 204 No Content

HTTP Request

POST https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}/apps/{APP_ID}

Unassign app

curl https://a.simplemdm.com/api/v1/assignment_groups/43/apps/21 \
  -u {API_KEY}: \
  -X DELETE

HTTP/1.1 204 No Content

HTTP Request

DELETE https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}/apps/{APP_ID}

Assign device group

curl https://a.simplemdm.com/api/v1/assignment_groups/43/device_groups/87 \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 204 No Content

HTTP Request

POST https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}/device_groups/{DEVICE_GROUP_ID}

Unassign device group

curl https://a.simplemdm.com/api/v1/assignment_groups/43/device_groups/87 \
  -u {API_KEY}: \
  -X DELETE

HTTP/1.1 204 No Content

HTTP Request

DELETE https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}/device_groups/{DEVICE_GROUP_ID}

Assign device

curl https://a.simplemdm.com/api/v1/assignment_groups/43/devices/87 \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 204 No Content

HTTP Request

POST https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}/devices/{DEVICE_ID}

Unassign device

curl https://a.simplemdm.com/api/v1/assignment_groups/43/device/87 \
  -u {API_KEY}: \
  -X DELETE

HTTP/1.1 204 No Content

HTTP Request

DELETE https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}/devices/{DEVICE_ID}

Push apps

Installs associated apps to associated devices.

curl https://a.simplemdm.com/api/v1/assignment_groups/43/push_apps \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

HTTP Request

POST https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}/push_apps

Update apps

Updates associated apps on associated devices.

curl https://a.simplemdm.com/api/v1/assignment_groups/43/update_apps \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

HTTP Request

POST https://a.simplemdm.com/api/v1/assignment_groups/{ASSIGNMENT_GROUP_ID}/update_apps

Custom Attributes

List all

curl https://a.simplemdm.com/api/v1/custom_attributes \
  -u {API_KEY}:

{
    "data": [
        {
            "type": "custom_attribute",
            "id": "email_address",
            "attributes": {
                "name": "email_address"
            }
        },
        {
            "type": "custom_attribute",
            "id": "full_name",
            "attributes": {
                "name": "full_name"
            }
        }
    ],
    "has_more": false
}

Show all custom attributes active in the account.

HTTP Request

GET https://a.simplemdm.com/api/v1/custom_attributes

Create

Define a new custom attribute for the account.

Argument Description
name Required. The name of the custom attribute. This name will be used when referencing the custom attribute throughout the app. Alphanumeric characters and underscores only. Case insensitive.

HTTP Request

POST https://a.simplemdm.com/api/v1/custom_attributes

Delete

Remove a custom attribute from the account. This will also remove all custom attribute values related to the custom attribute.

HTTP Request

DELETE https://a.simplemdm.com/api/v1/custom_attributes/{CUSTOM_ATTRIBUTE_ID}

Get values for device

Show all custom attribute values assigned to a device.

HTTP Request

GET https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/custom_attribute_values

Set value for device

Set the value of a custom attribute for a device.

Argument Description
value Required. The value to be assigned for the provided device and custom attribute.

HTTP Request

PUT https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/custom_attribute_values/{CUSTOM_ATTRIBUTE_ID}

Custom Configuration Profiles

List all

curl https://a.simplemdm.com/api/v1/custom_configuration_profiles \
  -u {API_KEY}:

{
    "data": [
        {
            "type": "custom_configuration_profile",
            "id": 293814,
            "attributes": {
                "name": "Munki Configuration"
            },
            "relationships": {
                "device_groups": {
                    "data": [
                        {
                            "type": "device group",
                            "id": 732444
                        }
                    ]
                }
            }
        }
    ],
    "has_more": false
}

HTTP Request

GET https://a.simplemdm.com/api/v1/custom_configuration_profiles

Create

Argument Description
name Required. A name for the profile.
mobileconfig Required. The mobileconfig file. Send as multipart/form-data.

HTTP Request

POST https://a.simplemdm.com/api/v1/custom_configuration_profiles/

Delete

HTTP Request

DELETE https://a.simplemdm.com/api/v1/custom_configuration_profiles/{PROFILE_ID}

Assign to device group

This action will cause the profile to push to all devices in the assigned device group.

HTTP Request

POST https://a.simplemdm.com/api/v1/custom_configuration_profiles/{PROFILE_ID}/device_groups/{DEVICE_GROUP_ID}

Unassign from device group

This action will cause the profile to be removed from all devices in the assigned device group.

HTTP Request

DELETE https://a.simplemdm.com/api/v1/custom_configuration_profiles/{PROFILE_ID}/device_groups/{DEVICE_GROUP_ID}

Devices

List all

Returns a listing of all devices in the account.

Argument Description
search Limit response to devices with matching name, UDID, serial number, MAC address, or phone number. 
curl https://a.simplemdm.com/api/v1/devices \
  -u {API_KEY}:

{
  "data": [
    {
      "type": "device",
      "id": 121,
      "attributes": {
        "name": "Mike's iPhone",
        "last_seen_at": "2015-10-01T18:38:47.277-07:00",
        "status": "enrolled",
        "device_name": "Mike's iPhone",
        "os_version": "9.0.2",
        "build_version": "13A452",
        "model_name": "iPhone 6",
        "model": "NG4W2LL",
        "product_name": "iPhone7,2",
        "unique_identifier": "4A08359C-1D3A-5D3E-939E-FFA6A561321D",
        "serial_number": "DNFJE9DNG5MG",
        "imei": "35 445506 652132 5",
        "meid": "35404596608032",
        "device_capacity": 55.62955093383789,
        "available_device_capacity": 15.19466781616211,
        "battery_level": "93%",
        "modem_firmware_version": "4.02.00",
        "iccid": "8914 8110 0002 8094 4264",
        "bluetooth_mac": "f0:db:e2:df:e9:11",
        "wifi_mac": "f0:db:e2:df:e9:2f",
        "current_carrier_network": "Verizon",
        "sim_carrier_network": "Verizon",
        "subscriber_carrier_network": "Verizon",
        "carrier_settings_version": "21.1",
        "phone_number": "5035551234",
        "voice_roaming_enabled": true,
        "data_roaming_enabled": false,
        "is_roaming": false,
        "subscriber_mcc": "311",
        "simmnc": "480",
        "current_mcc": "311",
        "current_mnc": "480",
        "hardware_encryption_caps": 3,
        "passcode_present": true,
        "passcode_compliant": true,
        "passcode_compliant_with_profiles": true,
        "subscriber_mnc": "480",
        "simmcc": "311",
        "is_supervised": false,
        "is_device_locator_service_enabled": true,
        "is_do_not_disturb_in_effect": false,
        "personal_hotspot_enabled": true,
        "itunes_store_account_is_active": true,
        "cellular_technology": 3,
        "last_cloud_backup_date": "2015-10-01T15:09:12.000-07:00",
        "is_activation_lock_enabled": true,
        "is_cloud_backup_enabled": true,
        "location_latitude": "75.13421212355",
        "location_longitude": "-14.313565422",
        "location_accuracy": "60",
        "location_updated_at": "2015-10-01T15:09:12.000-07:00"
      },
      "relationships": {
        "device_group": {
          "data": {
            "type": "device_group",
            "id": 37
          }
        }
      }
    },

    ...

  ],
  "has_more": false
}

HTTP Request

GET https://a.simplemdm.com/api/v1/devices

Retrieve one

curl https://a.simplemdm.com/api/v1/devices/121 \
  -u {API_KEY}:

{
  "data": {
    "type": "device",
    "id": 121,
    "attributes": {
      "name": "Mike's iPhone",
      "last_seen_at": "2015-10-01T18:38:47.277-07:00",
      "status": "enrolled",
      "device_name": "Mike's iPhone",
      "os_version": "9.0.2",
      "build_version": "13A452",
      "model_name": "iPhone 6",
      "model": "NG4W2LL",
      "product_name": "iPhone7,2",
      "serial_number": "DNFJE9DNG5MG",
      "imei": "35 445506 652132 5",
      "meid": "35404596608032",
      "device_capacity": 55.62955093383789,
      "available_device_capacity": 15.19466781616211,
      "battery_level": "93%",
      "modem_firmware_version": "4.02.00",
      "iccid": "8914 8110 0002 8094 4264",
      "bluetooth_mac": "f0:db:e2:df:e9:11",
      "wifi_mac": "f0:db:e2:df:e9:2f",
      "current_carrier_network": "Verizon",
      "sim_carrier_network": "Verizon",
      "subscriber_carrier_network": "Verizon",
      "carrier_settings_version": "21.1",
      "phone_number": "5035551234",
      "voice_roaming_enabled": true,
      "data_roaming_enabled": false,
      "is_roaming": false,
      "subscriber_mcc": "311",
      "simmnc": "480",
      "current_mcc": "311",
      "current_mnc": "480",
      "hardware_encryption_caps": 3,
      "passcode_present": true,
      "passcode_compliant": true,
      "passcode_compliant_with_profiles": true,
      "subscriber_mnc": "480",
      "simmcc": "311",
      "is_supervised": false,
      "is_device_locator_service_enabled": true,
      "is_do_not_disturb_in_effect": false,
      "personal_hotspot_enabled": true,
      "itunes_store_account_is_active": true,
      "cellular_technology": 3,
      "last_cloud_backup_date": "2015-10-01T15:09:12.000-07:00",
      "is_activation_lock_enabled": true,
      "is_cloud_backup_enabled": true,
      "location_latitude": "75.13421212355",
      "location_longitude": "-14.313565422",
      "location_accuracy": "60",
      "location_updated_at": "2015-10-01T15:09:12.000-07:00"
    },
    "relationships": {
      "device_group": {
        "data": {
          "type": "device_group",
          "id": 37
        }
      }
    }
  }
}

HTTP Request

GET https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}

Create

curl https://a.simplemdm.com/api/v1/devices/ \
  -d name="Sara's iPad" \
  -d group_id="41" \
  -u {API_KEY}:

{
    "data" => {
                 "type" => "device",
                   "id" => 980190963,
           "attributes" => {
                                         "name" => "Sara's iPad",
                                 "last_seen_at" => nil,
                                       "status" => "awaiting enrollment",
                               "enrollment_url" => "https://a.simplemdm.com/e/?c=63154796",
                                  "device_name" => nil,
                                   "os_version" => nil,
                                "build_version" => nil,
                                   "model_name" => "Unknown",
                                        "model" => nil,
                                 "product_name" => nil,
                            "unique_identifier" => nil,
                                "serial_number" => nil,
                                         "imei" => nil,
                                         "meid" => nil,
                              "device_capacity" => nil,
                    "available_device_capacity" => nil,
                                "battery_level" => nil,
                       "modem_firmware_version" => nil,
                                        "iccid" => nil,
                                "bluetooth_mac" => nil,
                                     "wifi_mac" => nil,
                      "current_carrier_network" => nil,
                          "sim_carrier_network" => nil,
                   "subscriber_carrier_network" => nil,
                     "carrier_settings_version" => nil,
                                 "phone_number" => nil,
                        "voice_roaming_enabled" => nil,
                         "data_roaming_enabled" => nil,
                                   "is_roaming" => nil,
                               "subscriber_mcc" => nil,
                                       "simmnc" => nil,
                                  "current_mcc" => nil,
                                  "current_mnc" => nil,
                     "hardware_encryption_caps" => nil,
                             "passcode_present" => nil,
                           "passcode_compliant" => nil,
             "passcode_compliant_with_profiles" => nil,
                                "is_supervised" => nil,
            "is_device_locator_service_enabled" => nil,
                  "is_do_not_disturb_in_effect" => nil,
                     "personal_hotspot_enabled" => nil,
               "itunes_store_account_is_active" => nil,
                          "cellular_technology" => nil,
                       "last_cloud_backup_date" => nil,
                   "is_activation_lock_enabled" => nil,
                      "is_cloud_backup_enabled" => nil,
                            "location_latitude" => nil,
                           "location_longitude" => nil,
                            "location_accuracy" => nil,
                          "location_updated_at" => nil
        },
        "relationships" => {
            "device_group" => {
                "data" => {
                    "type" => "device_group",
                      "id" => 41
                }
            }
        }
    }
}

Creates a new device object in SimpleMDM. The response body includes an enrollment URL that can be used once to enroll a physical device.

HTTP Request

POST https://a.simplemdm.com/api/v1/devices

Argument Description
name The name the device will show within SimpleMDM.
group_id The device group to assign the device to initially.

Update

curl https://a.simplemdm.com/api/v1/devices/121 \
  -X PATCH \  
  -d name="Ashley's iPad" \
  -u {API_KEY}:

{
  "data": {
    "type": "device",
    "id": 121,
    "attributes": {
      "name": "Ashley's iPad",
      "last_seen_at": "2015-10-01T18:38:47.277-07:00",
      "status": "enrolled",
      "device_name": "iPhone",
      "os_version": "9.3.2",
      "build_version": "13A452",
      "model_name": "iPhone 6",
      "model": "NG4W2LL",
      "product_name": "iPhone7,2",
      "serial_number": "DNFJE9DNG5MG",
      "imei": "35 445506 652132 5",
      "meid": "35404596608032",
      "device_capacity": 55.62955093383789,
      "available_device_capacity": 15.19466781616211,
      "battery_level": "93%",
      "modem_firmware_version": "4.02.00",
      "iccid": "8914 8110 0002 8094 4264",
      "bluetooth_mac": "f0:db:e2:df:e9:11",
      "wifi_mac": "f0:db:e2:df:e9:2f",
      "current_carrier_network": "Verizon",
      "sim_carrier_network": "Verizon",
      "subscriber_carrier_network": "Verizon",
      "carrier_settings_version": "21.1",
      "phone_number": "5035551234",
      "voice_roaming_enabled": true,
      "data_roaming_enabled": false,
      "is_roaming": false,
      "subscriber_mcc": "311",
      "simmnc": "480",
      "current_mcc": "311",
      "current_mnc": "480",
      "hardware_encryption_caps": 3,
      "passcode_present": true,
      "passcode_compliant": true,
      "passcode_compliant_with_profiles": true,
      "subscriber_mnc": "480",
      "simmcc": "311",
      "is_supervised": false,
      "is_device_locator_service_enabled": true,
      "is_do_not_disturb_in_effect": false,
      "personal_hotspot_enabled": true,
      "itunes_store_account_is_active": true,
      "cellular_technology": 3,
      "last_cloud_backup_date": "2015-10-01T15:09:12.000-07:00",
      "is_activation_lock_enabled": true,
      "is_cloud_backup_enabled": true,
      "location_latitude": "75.13421212355",
      "location_longitude": "-14.313565422",
      "location_accuracy": "60",
      "location_updated_at": "2015-10-01T15:09:12.000-07:00"
    },
    "relationships": {
      "device_group": {
        "data": {
          "type": "device_group",
          "id": 37
        }
      }
    }
  }
}

Update the SimpleMDM name or device name of a device object.

HTTP Request

PATCH https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}

Argument Description
name The name of the device within SimpleMDM.
device_name The name that appears on the device itself. Requires supervision. This operation is asynchronous and occurs when the device is online.

Delete

Unenroll a device and remove it from the account.

curl https://a.simplemdm.com/api/v1/devices/121 \
  -u {API_KEY}: \
  -X DELETE

HTTP/1.1 204

HTTP Request

DELETE https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}

List installed apps

curl https://a.simplemdm.com/api/v1/devices/121/installed_apps \
  -u {API_KEY}:

{
  "data": [
    {
      "type": "installed_app",
      "id": 578,
      "attributes": {
        "name": "1Password",
        "identifier": "com.agilebits.onepassword-ios",
        "version": "601004",
        "short_version": "6.0.1",
        "bundle_size": 93097984,
        "dynamic_size": 1056768,
        "managed": true,
        "discovered_at": "2015-10-01T18:02:13.611-07:00"
      }
    },
    {
      "type": "installed_app",
      "id": 618,
      "attributes": {
        "name": "Airbnb",
        "identifier": "com.airbnb.app",
        "version": "485",
        "short_version": "15.39",
        "bundle_size": 120823808,
        "dynamic_size": 27934720,
        "managed": false,
        "discovered_at": "2015-10-01T18:02:13.858-07:00"
      }
    },
    {
      "type": "installed_app",
      "id": 587,
      "attributes": {
        "name": "Bandsintown",
        "identifier": "com.bandsintown.bit",
        "version": "160",
        "short_version": "4.13.1",
        "bundle_size": 24756224,
        "dynamic_size": 18677760,
        "managed": false,
        "discovered_at": "2015-10-01T18:02:13.659-07:00"
      }
    },

    ...

  ],
  "has_more": false
}

Returns a listing of the apps installed on a device.

HTTP Request

GET https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/installed_apps

Push assigned apps

curl https://a.simplemdm.com/api/v1/devices/121/push_apps \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

You can use this method to push all assigned apps to a device that are not already installed.

HTTP Request

POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/push_apps

Restart

curl https://a.simplemdm.com/api/v1/devices/121/restart \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

This command sends a restart command to the device.

HTTP Request

POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/restart

Shutdown

curl https://a.simplemdm.com/api/v1/devices/121/shutdown \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

This command sends a shutdown command to the device.

HTTP Request

POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/shutdown

Lock

curl https://a.simplemdm.com/api/v1/devices/121/lock \
  -d message="Please call the number provided" \
  -d phone_number="5035551212" \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

You can use this method to lock a device and optionally display a message and phone number. The device can be unlocked with the existing passcode of the device.

HTTP Request

POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/lock

Argument Description
message Optional. The message to display on the lock screen.
phone_number Optional. The phone number to display on the lock screen.
pin Optional. OS X devices only. A 6-digit number that the device will require to be unlocked.

Clear passcode

curl https://a.simplemdm.com/api/v1/devices/121/clear_passcode \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

You can use this method to unlock and remove the passcode of a device.

HTTP Request

POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/clear_passcode

Wipe

curl https://a.simplemdm.com/api/v1/devices/121/wipe \
  -u {API_KEY}:
  -X POST

HTTP/1.1 202 Accepted

You can use this method to erase all content and settings stored on a device. The device will be unenrolled from SimpleMDM and returned to a factory default configuration.

HTTP Request

POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/wipe

Update OS

curl https://a.simplemdm.com/api/v1/devices/121/update_os \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

You can use this method to update a device to the latest OS version. Currently supported by iOS devices only.

HTTP Request

POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/update_os

Refresh

Request a refresh of the device information and app inventory. SimpleMDM will update the inventory information when the device responds to the request.

This command may return an HTTP 429 Too Many Requests if the API deems the frequency of requests to be excessive.

curl https://a.simplemdm.com/api/v1/devices/121/refresh \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202

HTTP Request

POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/refresh

Device Groups

A device group represents a collection of devices.

List all

curl https://a.simplemdm.com/api/v1/device_groups \
  -u {API_KEY}:

{
  "data": [
    {
      "type": "device_group",
      "id": 37,
      "attributes": {
        "name": "Remote Employees"
      }
    },
    {
      "type": "device_group",
      "id": 38,
      "attributes": {
        "name": "Executives"
      }
    }
  ],
  "has_more": false
}

HTTP Request

GET https://a.simplemdm.com/api/v1/device_groups

Retrieve one

curl https://a.simplemdm.com/api/v1/device_groups/37 \
  -u {API_KEY}:

{
  "data": {
    "type": "device_group",
    "id": 37,
    "attributes": {
      "name": "Remote Employees"
    }
  }
}

HTTP Request

GET https://a.simplemdm.com/api/v1/device_groups/{DEVICE_GROUP_ID}

Assign device

curl https://a.simplemdm.com/api/v1/device_groups/37/devices/121 \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202 No Content

HTTP Request

POST https://a.simplemdm.com/api/v1/device_groups/{DEVICE_GROUP_ID}/devices/{DEVICE_ID}

Enrollments

List All

curl https://a.simplemdm.com/api/v1/enrollments \
  -u {API_KEY}:

{  
  "data":[  
    {  
      "type":"enrollment",
      "id":3,
      "attributes":{  
        "url":"https://a.simplemdm.com/e/?c=31970277"
      },
      "relationships":{  
        "device_group":{  
          "data":{  
            "type":"device_group",
            "id":3
          }
        }
      }
    },
    {  
      "type":"enrollment",
      "id":4,
      "attributes":{  
        "url":"https://a.simplemdm.com/e/?c=30486333"
      },
      "relationships":{  
        "device_group":{  
          "data":{  
            "type":"device_group",
            "id":1
          }
        }
      }
    },
    {  
      "type":"enrollment",
      "id":5,
      "attributes":{  
        "url":"https://a.simplemdm.com/e/?c=86534893"
      },
      "relationships":{  
        "device":{  
          "data":{  
            "type":"device",
            "id":11
          }
        }
      }
    }
  ],
  "has_more":false
}

HTTP Request

GET https://a.simplemdm.com/api/v1/enrollments

Show

curl https://a.simplemdm.com/api/v1/enrollments/5 \
  -u {API_KEY}:

{  
  "data":{  
    "type":"enrollment",
    "id":5,
    "attributes":{  
      "url":"https://a.simplemdm.com/e/?c=86534893"
    },
    "relationships":{  
      "device":{  
        "data":{  
          "type":"device",
          "id":11
        }
      }
    }
  }
}

HTTP Request

GET https://a.simplemdm.com/api/v1/enrollments/{ENROLLMENT_ID}

Send Invitation

Send an enrollment invitation to an email address or phone number.

Argument Description
contact Required. An email address or phone number. Prefix international numbers with a +.

HTTP Request

POST https://a.simplemdm.com/api/v1/enrollments/{ENROLLMENT_ID}/invitations

Delete

curl https://a.simplemdm.com/api/v1/enrollments \
  -u {API_KEY}:

HTTP Request

GET https://a.simplemdm.com/api/v1/enrollments

Installed Apps

Installed apps represent apps that are installed and exist on devices.

List for device

Refer to Device - List installed apps.

Retrieve one

curl https://a.simplemdm.com/api/v1/installed_apps/6632 \
  -u {API_KEY}:

{
    "data": {
        "type": "installed_app",
        "id": 6632,
        "attributes": {
            "name": "Sunset Run",
            "identifier": "com.fuilana.SunsetRun",
            "version": "2.2.1.1",
            "short_version": "2.2.1",
            "bundle_size": 15720448,
            "dynamic_size": 16384,
            "managed": true,
            "discovered_at": "2016-10-12T15:54:16.116-07:00"
        }
    }
}

HTTP Request

GET https://a.simplemdm.com/api/v1/installed_apps/{INSTALLED_APP_ID}

Install update

curl https://a.simplemdm.com/api/v1/installed_apps/{INSTALLED_APP_ID}/update \
  -u {API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

This submits a request to the device to update the specified app to the latest version. The app must be managed for this request to succeed.

HTTP Request

POST https://a.simplemdm.com/api/v1/installed_apps/{INSTALLED_APP_ID}/update

Uninstall

curl https://a.simplemdm.com/api/v1/installed_apps/{INSTALLED_APP_ID} \
  -u {API_KEY}: \
  -X DELETE

HTTP/1.1 202 Accepted

This submits a request to the device to uninstall the specified app. The app must be managed for this request to succeed.

HTTP Request

DELETE https://a.simplemdm.com/api/v1/installed_apps/{INSTALLED_APP_ID}

Managed App Configs

Create, modify, and remove the managed app configuration associated with an app.

Get

Retrieve the managed configs for an app.

curl https://a.simplemdm.com/api/v1/apps/{APP_ID}/managed_configs \
  -u {API_KEY}:

{
    "data": [
        {
            "type": "managed_config",
            "id": 14,
            "attributes": {
                "key": "customer_name",
                "value": "ACME Inc.",
                "value_type": "string"
            }
        },
        {
            "type": "managed_config",
            "id": 32,
            "attributes": {
                "key": "User IDs",
                "value": "1,53,3",
                "value_type": "integer array"
            }
        },
        {
            "type": "managed_config",
            "id": 13,
            "attributes": {
                "key": "Device values",
                "value": "\"$imei\",\"$udid\"",
                "value_type": "string array"
            }
        }
    ],
    "has_more": false
}

HTTP Request

GET https://a.simplemdm.com/api/v1/apps/{APP_ID}/managed_configs

Create

Argument Description
key Required.
value Valid values are based on the value_type specified. See table below.
value_type The type of the value. See valid options below.

Value Types and Value Formats

Value Type Value Format
boolean 0 or 1
date Timestamp format with timezone. Most standards should parse correctly. Example: 2017-01-01T12:31:15-07:00
float Float value. Example: 0.123
float array Floats separated by commas. Example: 0.123,923.1,42
integer Integer value. Example: 32
integer array Integers separated by commas. Example 1,452,-129
string Example: This is a string
string array Strings in quotes an dseparated by commas. Example: “First string”,“Second string”

Delete

DELETE https://a.simplemdm.com/api/v1/apps/{APP_ID}/managed_configs/{MANAGED_CONFIG_ID}

Push Updates

Push any updates to the managed configurations for an app to all devices. This is not necessary when making managed config changes through the UI. This is necessary after making changes through the API.

POST https://a.simplemdm.com/api/v1/apps/{APP_ID}/managed_configs/push

Push Certificate

Methods related to the Apple Push Notification Certificate utilized by the account.

Show

Show details related to the current push certificate being used.

HTTP Request

GET https://a.simplemdm.com/api/v1/push_certificate

curl https://a.simplemdm.com/api/v1/push_certificate \
  -u {API_KEY}:

{
    "data": {
        "type": "push_certificate",
        "attributes": {
            "apple_id": "devops@example.org",
            "expires_at": "2017-09-21T15:28:34.000+00:00"
        }
    }
}

Update

Upload a new certificate and replace the existing certificate for your account.

HTTP Request

PUT https://a.simplemdm.com/api/v1/push_certificate

Argument Description
file Required. The push certificate as provided by Apple. Send as multipart/form-data.
apple_id Optional. The email address of the apple ID the push certificate was generated with. 
curl https://a.simplemdm.com/api/v1/push_certificate/scsr \
  -F file@apns.cert \
  -F apple_id=admin@example.org \
  -u {API_KEY}:

{
    "data": {
        "type": "push_certificate",
        "attributes": {
            "apple_id": "admin@example.org",
            "expires_at": "2020-09-21T15:28:34.000+00:00"
        }
    }
}

Get Signed CSR

Download a signed CSR file. This file is provided to Apple when creating and renewing a push certificate. The API returns a base64 encoded plist for upload to the Apple Push Certificates Portal. The value of the “data” key can be uploaded to Apple as-is.

HTTP Request

GET https://a.simplemdm.com/api/v1/push_certificate/scsr

curl https://a.simplemdm.com/api/v1/push_certificate/scsr \
  -u {API_KEY}:

{
    "data": "VUVRVZ5HSlhkMmRrYlZaNVl6SnNkbUpxTUdsTlV6UjNTV2xDYkdKdFRuWmFS\nMngxV25vd2FWWldVa2RNClZHZHBVSG8wUzFCRFJrVlVNRTVWQ2xkV1FrWkpT\nRUp6WVZoT01FbEdRbFpSYTNoS1VYbEJhVXhUT0haUgpXRUozWWtkVloxRXlP\nWFJaU0ZZd1dsaEpka3d3QmtSa3BwVGxWb2VWWkgKYkRKa01V\nSkVXakJzYjFWclJYWmlhMFpUVGxWNFdWSkdVWGRsYkUxTFdsVTRjbU5FU1RB\nSUlRSM1VWVTFid3BSCmFscDBUVVpz\nUWsxWGFGUlRWMWw2VFcweFlXTlZkRVpVUjFaSlZuazVlVmx0VW5WT01VVTVV\nRkZ2T0V3egpUakJqYld4MVdubzBTMUJET1dzS1lWZE9NRkJuYnpoTU0wSnpZ\nVmhPTUZCbmJ6MEsT\n"
}

Webhooks

Webhooks allow you to receive an HTTP POST to the URL(s) of your choosing when certain events occur in your SimpleMDM account. All of our webhook events contain data serialized as JSON. If you’d like to be notified (with data) every time a device is enrolled, for instance, you’ll want to use webhooks.

{
  "type": "event.type",
  "at": "2000-01-01T12:00:00.000-07:00",
  "data": {}
}

Webhook requests include a JSON body which describes the event type, the time of occurrence, and may include additional metadata in the “data” field. This metadata varies depending upon the event type.

The metadata included with webhook events is purposefully minimal. If additional information in required about related objects, the SimpleMDM API may be queried for additional information.

Events

The current events are currently available: