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",
"subscription": {
"licenses": {
"total": 500,
"available": 123
}
}
}
}
}
Retrieve information about your account. Subscription information is only available for accounts on a manual billing plan.
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 deploy_to=outdated \
-X 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. |
deploy_to | Deploy the app to associated devices immediately after the app has been uploaded and processed. Possible values are none , outdated or all . When set to outdated , and a newer version of an app has been uploaded, SimpleMDM will deploy the app to all associated devices with an outdated version of the app installed. When set to all , SimpleMDM will deploy to all associated devices regardless of the version of the app currently installed. If set to none then the app will not be immediately deployed to any devices as a result of this API call. Defaults to none |
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",
"default_value": "user@example.org"
}
},
{
"type": "custom_attribute",
"id": "full_name",
"attributes": {
"name": "full_name",
"default_value": "not provided"
}
}
],
"has_more": false
}
Show all custom attributes active in the account.
HTTP Request
GET https://a.simplemdm.com/api/v1/custom_attributes
Retrieve one
curl https://a.simplemdm.com/api/v1/custom_attributes/email_address \
-u {API_KEY}:
{
"data": {
"type": "custom_attribute",
"id": "email_address",
"attributes": {
"name": "email_address",
"default_value": "user@example.org"
}
}
}
HTTP Request
GET https://a.simplemdm.com/api/v1/custom_attributes/{CUSTOM_ATTRIBUTE_ID}
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. |
default_value | Optional. The value that will be used if a value is not provided elsewhere. |
HTTP Request
POST https://a.simplemdm.com/api/v1/custom_attributes
Update
Update a custom attribute for the account.
Argument | Description |
---|---|
default_value | The value that will be used if a value is not provided elsewhere. |
HTTP Request
POST https://a.simplemdm.com/api/v1/custom_attributes/{CUSTOM_ATTRIBUTE_ID}
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_NAME}
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",
"profile_identifier": "com.unwiredmdm.aabc717175a3467b93af177aa5f1992d"
"user_scope": true,
"attribute_support": false
},
"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. |
user_scope | Optional. A boolean true or false. If false, deploy as a device profile instead of a user profile for macOS devices. Defaults to true. |
attribute_support | Optional. A boolean true or false. When enabled, SimpleMDM will process variables in the uploaded profile. Defaults to false. |
HTTP Request
POST https://a.simplemdm.com/api/v1/custom_configuration_profiles/
Update
Argument | Description |
---|---|
name | Optional. Change the name of the profile. |
mobileconfig | Optional. Update the mobileconfig file. Send as multipart/form-data. |
user_scope | Optional. A boolean true or false. If false, deploy as a device profile instead of a user profile for macOS devices. |
attribute_support | Optional. A boolean true or false. When enabled, SimpleMDM will process variables in the uploaded profile. |
HTTP Request
PATCH https://a.simplemdm.com/api/v1/custom_configuration_profiles/{PROFILE_ID}
Download
Download the contents of the custom configuration profile.
HTTP Request
GET https://a.simplemdm.com/api/v1/custom_configuration_profiles/{PROFILE_ID}/download
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}
Assign to device
This action will cause the profile to push to the specified device.
HTTP Request
POST https://a.simplemdm.com/api/v1/custom_configuration_profiles/{PROFILE_ID}/devices/{DEVICE_ID}
Unassign from device
This action will cause the profile to be removed from the specified device.
HTTP Request
DELETE https://a.simplemdm.com/api/v1/custom_configuration_profiles/{PROFILE_ID}/devices/{DEVICE_ID}
DEP Servers
List all
Returns a list of Apple Business Manager server associations, which are used for the purposes of Automated Enrollment (formerly Apple DEP or Device Enrollment Program). These associations exist as "Enrollments" within the SimpleMDM admin interface.
HTTP Request
GET https://a.simplemdm.com/api/v1/dep_servers
Retrieve one
HTTP Request
GET https://a.simplemdm.com/api/v1/dep_servers/{DEP_SERVER_ID}
Sync with Apple
DEP server records are automatically syncronized with Apple every couple of hours. This provokes a manual sync.
HTTP Request
POST https://a.simplemdm.com/api/v1/dep_servers/{DEP_SERVER_ID}/sync
List DEP devices
Returns a listing of device records associated with the DEP server, as provided by Apple. These DEP devices do not necessarily have corresponding SimpleMDM device records.
HTTP Request
GET https://a.simplemdm.com/api/v1/dep_servers/{DEP_SERVER_ID}/dep_devices
Retrieve one DEP device
HTTP Request
GET https://a.simplemdm.com/api/v1/dep_servers/{DEP_SERVER_ID}/dep_devices/{DEP_DEVICE_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, IMEI, MAC address, or phone number. |
include_awaiting_enrollment | When true, returns all devices including those in the awaiting_enrollment state. When false, does not return devices in the awaiting_enrollment state. Defaults to false. |
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 profiles
curl https://a.simplemdm.com/api/v1/devices/121/profiles \
-u {API_KEY}:
{
"data": [
{
"type": "custom_configuration_profile",
"id": 13,
"attributes": {
"name": "Disable AFP",
"profile_identifier": "com.unwiredmdm.aabc717175a3467b93af177aa5f1992b",
"user_scope": false,
"attribute_support": false
}
}
],
"has_more": false
}
Returns a listing of profiles that are directly assigned to the device. Profiles assigned through groups are not shown. Per-device profiles created through the "Accounts" tab of the UI are not shown.
HTTP Request
GET https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/profiles
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
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
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
Shut down
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 | Required for macOS devices. Not supported by iOS. A 6-digit number that the device will require to be unlocked. |
Lost mode actions
Refer to Lost Mode.
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
Clear firmware password
curl https://a.simplemdm.com/api/v1/devices/121/clear_firmware_password \
-u {API_KEY}: \
-X POST
HTTP/1.1 202 Accepted
You can use this method to remove the firmware password from a device. The firmware password must have been originally set using SimpleMDM for this to complete successfully.
HTTP Request
POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/clear_firmware_password
Rotate FileVault recovery key
curl https://a.simplemdm.com/api/v1/devices/121/rotate_filevault_key \
-u {API_KEY}: \
-X POST
HTTP/1.1 202 Accepted
You can use this method to rotate the filevault recovery key for a device. SimpleMDM must be aware of the current recovery key or this command will fail.
HTTP Request
POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/rotate_filevault_key
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
Argument | Description |
---|---|
pin | Required for macOS devices that do not have the T2 chip. Not supported by iOS or macOS devices with a T2 chip. A 6-digit number that the device will require to be unlocked. |
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
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}
Clone
Create a copy of a device group with the same configurations as the original. The new device group will not have any devices assigned to it initially.
curl https://a.simplemdm.com/api/v1/device_groups/37/clone \
-u {API_KEY}: \
-X POST
{
"data": {
"type": "device_group",
"id": 38,
"attributes": {
"name": "Remote Employees (1)"
},
"relationships": {
"devices": {
"data": []
}
}
}
}
HTTP Request
POST https://a.simplemdm.com/api/v1/device_groups/{DEVICE_GROUP_ID}/clone
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}
Logs
View Logged events for device and admin interactions.
List All
Retrieve the logs.
curl https://a.simplemdm.com/api/v1/logs \
-u {API_KEY}:
{
"data": [
{
"type": "log",
"id": "abcde123456",
"attributes": {
"namespace": "admin",
"event_type": "user.signed_in",
"level": 0,
"source": "admin ui",
"at": "11/06/19 18:27:41",
"metadata": {},
"relationships": {
"account": {
"data": {
"type": "account",
"id": 123456
}
},
"user": {
"data": {
"type": "user",
"id": 123456,
"email": "support@simplemdm.com"
}
}
}
}
}
],
"has_more": true
}
HTTP Request
GET https://a.simplemdm.com/api/v1/logs
Lost Mode
Enable
Activate lost mode on a device.
HTTP Request
POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/lost_mode
Argument | Description |
---|---|
message | A message to be delivered to the user of the device. |
phone_number | A contact number to reach the device's administrator. |
footnote | An additional message to be displayed at the bottom of the device. |
A message or phone number must be added to the request in order to enable lost mode for a device.
Disable
Disable lost mode on a device.
HTTP Request
DELETE https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/lost_mode
Play a sound
Request that the device play a sound to assist with locating it.
HTTP Request
POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/lost_mode/play_sound
Update location
Request that the device provide its current, up-to-date location. Location data can be viewed using the devices endpoint.
HTTP Request
POST https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/lost_mode/update_location
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:
- device.changed_group
- device.enrolled
- device.unenrolled