NAV

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
}

Supports pagination.

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}

List installs

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

{
  "data": [
    {
      "type": "installed_app",
      "id": 26409,
      "attributes": {
        "name": "Deliveries",
        "identifier": "com.junecloud.Deliveries",
        "version": "9.2.1",
        "short_version": "9.2.1",
        "bundle_size": 56163003,
        "dynamic_size": null,
        "managed": false,
        "discovered_at": "2021-11-08T09:02:07.000-08:00",
        "last_seen_at": "2021-12-22T13:01:58.000-08:00"
      },
      "relationships": {
        "device": {
          "data": {
            "type": "device",
            "id": 7
          }
        }
      }
    },
    {
      "type": "installed_app",
      "id": 34943,
      "attributes": {
        "name": "Deliveries",
        "identifier": "com.junecloud.Deliveries",
        "version": "1311",
        "short_version": "9.2.1",
        "bundle_size": 21204992,
        "dynamic_size": 139264,
        "managed": true,
        "discovered_at": "2021-12-16T14:25:54.000-08:00",
        "last_seen_at": "2021-12-22T13:00:57.000-08:00"
      },
      "relationships": {
        "device": {
          "data": {
            "type": "device",
            "id": 3
          }
        }
      }
    }
  ],
  "has_more": false
}

Returns a listing of the devices that an app is installed on. Supports pagination.

HTTP Request

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

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. Supports pagination.

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

PATCH 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.

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

{
  "data": [
    {
      "type": "custom_attribute_value",
      "id": "my_first_custom_attribute",
      "attributes": {
        "value": "hello"
      }
    },
    {
      "type": "custom_attribute_value",
      "id": "my_other_custom_attribute",
      "attributes": {
        "value": ""
      }
    }
  ]
}

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.
curl "https://a.simplemdm.com/api/v1/devices/1/custom_attribute_values/my_other_custom_attribute" \
  -u {API_KEY}: \
  -d value="test" \
  -X "PUT"

{
  "data": {
    "type": "custom_attribute_value",
    "id": "my_other_custom_attribute",
    "attributes": {
      "value": "test"
    }
  }
}

HTTP Request

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

Get values for group

Show all custom attribute values assigned to a device group.

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

{
  "data": [
    {
      "type": "custom_attribute_value",
      "id": "my_first_custom_attribute",
      "attributes": {
        "value": "hello"
      }
    },
    {
      "type": "custom_attribute_value",
      "id": "my_other_custom_attribute",
      "attributes": {
        "value": ""
      }
    }
  ]
}

HTTP Request

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

Set value for group

Set the value of a custom attribute for a device group.

Argument Description
value Required. The value to be assigned for the provided group and custom attribute.
curl "https://a.simplemdm.com/api/v1/device_groups/1/custom_attribute_values/my_other_custom_attribute" \
  -u {API_KEY}: \
  -d value="test" \
  -X "PUT"

{
  "data": {
    "type": "custom_attribute_value",
    "id": "my_other_custom_attribute",
    "attributes": {
      "value": "test"
    }
  }
}

HTTP Request

PUT https://a.simplemdm.com/api/v1/device_groups/{DEVICE_GROUP_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,
                "group_count": 2,
                "device_count": 4
            },
            "relationships": {
                "device_groups": {
                    "data": [
                        {
                            "type": "device group",
                            "id": 732444
                        }
                    ]
                }
            }
        }
    ],
    "has_more": false
}

Supports pagination.

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. Supports pagination.

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

{
  "data": [
    {
      "type": "dep_server",
      "id": 1,
      "attributes": {
        "server_name": "My DEP MDM Server",
        "organization_name": "SimpleMDM",
        "token_expires_at": "2023-02-03T10:57:07.000-08:00",
        "last_synced_at": "2022-02-05T06:00:05.000-08:00"
      }
    },
    {
      "type": "dep_server",
      "id": 2,
      "attributes": {
        "server_name": "Another MDM Server",
        "organization_name": "Acme Corp",
        "token_expires_at": "2023-02-03T10:57:07.000-08:00",
        "last_synced_at": "2022-02-05T06:00:05.000-08:00"
      }
    }
  ],
  "has_more": false
}

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 synchronized 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. Supports pagination.

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. Supports pagination.

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": "2021-07-13T16:00:54.000-07:00",
        "last_seen_ip": "203.0.113.0",
        "status": "enrolled",
        "enrollment_channels": [
          "device"
        ],
        "device_name": "Mike's iPhone",
        "os_version": "14.7",
        "build_version": "18G5042c",
        "model_name": "iPhone 7",
        "model": "NG4W2LL",
        "product_name": "iPhone9,1",
        "unique_identifier": "4A08359C-1D3A-5D3E-939E-FFA6A561321D",
        "serial_number": "DNFJE9DNG5MG",
        "processor_architecture": null,
        "imei": "35 445506 652132 5",
        "meid": "35404596608032",
        "device_capacity": 128.0,
        "available_device_capacity": 119.07,
        "battery_level": "100%",
        "modem_firmware_version": "8.80.00",
        "iccid": "8914 8110 0002 8094 4264",
        "bluetooth_mac": "f0:db:e2:df:e9:11",
        "ethernet_macs": [],
        "wifi_mac": "f0:db:e2:df:e9:2f",
        "current_carrier_network": "Verizon",
        "sim_carrier_network": null,
        "subscriber_carrier_network": "Verizon",
        "carrier_settings_version": "46.0.1",
        "phone_number": "+15555555555",
        "voice_roaming_enabled": true,
        "data_roaming_enabled": false,
        "is_roaming": false,
        "subscriber_mcc": "311",
        "subscriber_mnc": "480",
        "simmnc": null,
        "current_mcc": "310",
        "current_mnc": "00",
        "hardware_encryption_caps": 3,
        "passcode_present": false,
        "passcode_compliant": true,
        "passcode_compliant_with_profiles": true,
        "is_supervised": true,
        "is_dep_enrollment": false,
        "is_user_approved_enrollment": null,
        "is_device_locator_service_enabled": false,
        "is_do_not_disturb_in_effect": false,
        "personal_hotspot_enabled": false,
        "itunes_store_account_is_active": false,
        "cellular_technology": 3,
        "last_cloud_backup_date": null,
        "is_activation_lock_enabled": false,
        "is_cloud_backup_enabled": false,
        "filevault_enabled": false,
        "filevault_recovery_key": null,
        "firmware_password_enabled": false,
        "recovery_lock_password_enabled": false,
        "remote_desktop_enabled": false,
        "firmware_password": null,
        "recovery_lock_password": null,
        "firewall": {
          "enabled": null,
          "block_all_incoming": null,
          "stealth_mode": null
        },
        "system_integrity_protection_enabled": null,
        "os_update": {
          "automatic_os_installation_enabled": null,
          "automatic_app_installation_enabled": null,
          "automatic_check_enabled": null,
          "automatic_security_updates_enabled": null,
          "background_download_enabled": null,
          "catalog_url": null,
          "default_catalog": null,
          "perform_periodic_check": null,
          "previous_scan_date": null,
          "previous_scan_result": null
        },
        "location_latitude": null,
        "location_longitude": null,
        "location_accuracy": null,
        "location_updated_at": null
      },
      "relationships": {
        "device_group": {
          "data": {
            "type": "device_group",
            "id": 1
          }
        }
      }
    },

    ...

  ],
  "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": "2021-07-13T16:00:54.000-07:00",
      "last_seen_ip": "203.0.113.0",
      "status": "enrolled",
      "enrollment_channels": [
        "device"
      ],
      "device_name": "Mike's iPhone",
      "os_version": "14.7",
      "build_version": "18G5042c",
      "model_name": "iPhone 7",
      "model": "NG4W2LL",
      "product_name": "iPhone9,1",
      "unique_identifier": "4A08359C-1D3A-5D3E-939E-FFA6A561321D",
      "serial_number": "DNFJE9DNG5MG",
      "processor_architecture": null,
      "imei": "35 445506 652132 5",
      "meid": "35404596608032",
      "device_capacity": 128.0,
      "available_device_capacity": 119.07,
      "battery_level": "100%",
      "modem_firmware_version": "8.80.00",
      "iccid": "8914 8110 0002 8094 4264",
      "bluetooth_mac": "f0:db:e2:df:e9:11",
      "ethernet_macs": [],
      "wifi_mac": "f0:db:e2:df:e9:2f",
      "current_carrier_network": "Verizon",
      "sim_carrier_network": null,
      "subscriber_carrier_network": "Verizon",
      "carrier_settings_version": "46.0.1",
      "phone_number": "+15555555555",
      "voice_roaming_enabled": true,
      "data_roaming_enabled": false,
      "is_roaming": false,
      "subscriber_mcc": "311",
      "subscriber_mnc": "480",
      "simmnc": null,
      "current_mcc": "310",
      "current_mnc": "00",
      "hardware_encryption_caps": 3,
      "passcode_present": false,
      "passcode_compliant": true,
      "passcode_compliant_with_profiles": true,
      "is_supervised": true,
      "is_dep_enrollment": false,
      "is_user_approved_enrollment": null,
      "is_device_locator_service_enabled": false,
      "is_do_not_disturb_in_effect": false,
      "personal_hotspot_enabled": false,
      "itunes_store_account_is_active": false,
      "cellular_technology": 3,
      "last_cloud_backup_date": null,
      "is_activation_lock_enabled": false,
      "is_cloud_backup_enabled": false,
      "filevault_enabled": false,
      "filevault_recovery_key": null,
      "firmware_password_enabled": false,
      "recovery_lock_password_enabled": false,
      "remote_desktop_enabled": false,
      "firmware_password": null,
      "recovery_lock_password": null,
      "firewall": {
        "enabled": null,
        "block_all_incoming": null,
        "stealth_mode": null
      },
      "system_integrity_protection_enabled": null,
      "os_update": {
        "automatic_os_installation_enabled": null,
        "automatic_app_installation_enabled": null,
        "automatic_check_enabled": null,
        "automatic_security_updates_enabled": null,
        "background_download_enabled": null,
        "catalog_url": null,
        "default_catalog": null,
        "perform_periodic_check": null,
        "previous_scan_date": null,
        "previous_scan_result": null
      },
      "location_latitude": null,
      "location_longitude": null,
      "location_accuracy": null,
      "location_updated_at": null
    },
    "relationships": {
      "device_group": {
        "data": {
          "type": "device_group",
          "id": 1
        }
      }
    }
  }
}

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,
                                 "last_seen_ip" => 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",
      "last_seen_ip": "203.0.113.0",
      "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. Supports pagination.

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",
        "last_seen_at": "2021-12-22T13:00:57.000-08: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",
        "last_seen_at": "2021-12-22T13:00:57.000-08: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",
        "last_seen_at": "2021-12-22T13:00:57.000-08:00"
      }
    },

    ...

  ],
  "has_more": false
}

Returns a listing of the apps installed on a device. Supports pagination.

HTTP Request

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

List Users

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

Returns a listing of the user accounts on a device. Supports pagination.

Available for macOS devices only.

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

{
  "data": [
    {
      "type": "device_user",
      "id": 5,
      "attributes": {
        "username": "userone",
        "full_name": "User One",
        "uid": 501,
        "user_guid": "2DEE464E-0C21-4D0C-8B5B-0F74655ED54E",
        "data_quota": null,
        "data_used": null,
        "data_to_sync": false,
        "secure_token": true,
        "logged_in": true,
        "mobile_account": false
      }
    },
    {
      "type": "device_user",
      "id": 6,
      "attributes": {
        "username": "usertwo",
        "full_name": "User Two",
        "uid": 502,
        "user_guid": "AABBA42B-8078-48BA-9DA7-2CB6B0BC7272",
        "data_quota": null,
        "data_used": null,
        "data_to_sync": false,
        "secure_token": true,
        "logged_in": false,
        "mobile_account": false
      }
    }
  ],
  "has_more": false
}

Delete User

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

Deletes a user from the device.

Available for supervised macOS devices only. This command will return HTTP 422 Unprocessable Entity for unsupported devices.

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

HTTP/1.1 202 Accepted

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

Argument Description
rebuild_kernel_cache Optional. Rebuild the kernel cache during restart. Requires macOS 11 or later. Defaults to false
notify_user Optional. If a user is signed in, prompt them to optionally restart the device. Requires macOS 11.3 or later. Defaults to false.

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. Supported on iOS 7.0+ and macOS 10.14+.
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

Enable Remote Desktop

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

HTTP/1.1 202 Accepted

You can use this method to enable remote desktop. Supported by macOS 10.14.4+ devices only.

HTTP Request

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

Disable Remote Desktop

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

HTTP/1.1 202 Accepted

You can use this method to disable remote desktop. Supported by macOS 10.14.4+ devices only.

HTTP Request

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

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
}

Supports pagination.

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
}

Supports pagination.

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",
            "last_seen_at": "2021-12-22T13:00:57.000-08:00"
        }
    }
}

HTTP Request

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

Request management of app

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

HTTP/1.1 202 Accepted

Requests management of an unmanaged app installed on a device.

Available for iOS, tvOS, and macOS (11+) devices.

HTTP Request

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

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.

Argument Description
serial_number Limit response to the logs of a single device. An empty argument defaults to returning all logs

List All

Retrieve the logs. Supports pagination.

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

Retrieve one

Retrieve a specific log entry.

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

{
  "data": {
    "type": "log",
    "id": "964595dfd5be464a82cbb9019f55d82b",
    "attributes": {
      "namespace": "device",
      "event_type": "script.ran",
      "level": "info",
      "source": "device",
      "at": "06/01/22 11:26:19",
      "metadata": {
        "name": "My Script",
        "job_status": "0",
        "job_response": "Hello World!\n"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": 1,
            "api_key": "Test API"
          }
        },
        "device": {
          "data": {
            "type": "device",
            "serial_number": "ZP9XH0X52C",
            "udid": "868F7125-B1AF-5139-B71F-99D68768AABB"
          }
        }
      }
    }
  }
}

HTTP Request

GET https://a.simplemdm.com/api/v1/logs/{LOG_ID}

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

HTTP Request

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

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"
curl "https://a.simplemdm.com/api/v1/apps/10042/managed_configs" \
  -X POST \
  -u {API_KEY}: \
  -F key="serverURL" \
  -F value="http://example.com" \
  -F value_type="string"

{
  "data": {
    "type": "managed_config",
    "id": 2,
    "attributes": {
      "key": "serverURL",
      "value": "http://example.com",
      "value_type": "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"
}

Scripts

Scripts functionality is not currently available for some subscriptions. For further assistance, please contact support.

List all

Returns a listing of all scripts in the account. Supports pagination.

HTTP Request

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

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

{
  "data": [
    {
      "type": "script",
      "id": 31,
      "attributes": {
        "name": "Say hi",
        "content": "#!/bin/bash\r\ncurrentUser=$( echo \"show State:/Users/ConsoleUser\" | scutil | awk '/Name :/ { print $3 }' )\r\nuid=$(id -u \"$currentUser\")\r\nlaunchctl asuser $uid say hi",
        "variable_support": false,
        "created_at": "2022-01-05T11:33:33.600-08:00",
        "updated_at": "2022-01-05T11:33:33.600-08:00"
      }
    },
    {
      "type": "script",
      "id": 32,
      "attributes": {
        "name": "script-8ilpJ",
        "content": "#!/bin/bash\necho \"Hello!\"",
        "variable_support": true,
        "created_at": "2022-05-31T10:56:50.232-07:00",
        "updated_at": "2022-05-31T10:56:50.232-07:00"
      }
    }
  ],
  "has_more": false
}

Retrieve one

HTTP Request

GET https://a.simplemdm.com/api/v1/scripts/{SCRIPT_ID}

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

{
  "data": {
    "type": "script",
    "id": 32,
    "attributes": {
      "name": "script-8ilpJ",
      "content": "#!/bin/bash\necho \"Hello!\"",
      "variable_support": true,
      "created_at": "2022-05-31T10:56:50.232-07:00",
      "updated_at": "2022-05-31T10:56:50.232-07:00"
    }
  }
}

Create

You can use this method to upload a new script to your account.

HTTP Request

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

Argument Description
name Required. The name for the script. This is how it will appear in the Admin UI.
variable_support Whether or not to enable variable support in this script. Pass 1 to enable, 0 to disable. Defaults to false
file Required. A file containing the script content. All scripts must begin with a valid shebang such as #!/bin/sh to be processed. File should be provided as multipart/form-data.
curl "https://a.simplemdm.com/api/v1/scripts" \
  -X POST \
  -u {API_KEY}: \
  -F name="My New Script" \
  -F variable_support=1 \
  -F file=@my_new_script.sh


{
  "data": {
    "type": "script",
    "id": 35,
    "attributes": {
      "name": "My New Script",
      "content": "#!/bin/bash\necho \"Hello!\"",
      "variable_support": true,
      "created_at": "2022-06-01T12:30:01.590-07:00",
      "updated_at": "2022-06-01T12:30:01.590-07:00"
    }
  }
}

Update

You can use this method to update an existing script in your account. Any existing Script Jobs will not be changed.

HTTP Request

PATCH https://a.simplemdm.com/api/v1/scripts/{SCRIPT_ID}

Argument Description
name The name for the script. This is how it will appear in the Admin UI.
variable_support Whether or not to enable variable support in this script. Pass 1 to enable, 0 to disable. Defaults to false
file A file containing the script content. All scripts must begin with a valid shebang such as #!/bin/sh to be processed. File should be provided as multipart/form-data.
curl "https://a.simplemdm.com/api/v1/scripts/35" \
  -X PATCH \
  -u {API_KEY}: \
  -F name="My Renamed Script" \
  -F variable_support=0 \
  -F file=@my_updated_script.sh


{
  "data": {
    "type": "script",
    "id": 35,
    "attributes": {
      "name": "My Renamed Script",
      "content": "#!/bin/bash\necho \"Goodbye!\"",
      "variable_support": false,
      "created_at": "2022-06-01T12:30:01.590-07:00",
      "updated_at": "2022-06-01T12:30:01.590-07:00"
    }
  }
}

Delete

You can use this method to delete a script from your account. Any existing Script Jobs will not be changed.

HTTP Request

DELETE https://a.simplemdm.com/api/v1/scripts/{SCRIPT_ID}

curl "https://a.simplemdm.com/api/v1/scripts/35" \
  -X DELETE \

HTTP/1.1 204 No Content

Script Jobs

Scripts functionality is not currently available for some subscriptions. For further assistance, please contact support.

List all

Jobs represent scripts that have been set to run on a collection of devices. Jobs remain listed for one month. Supports pagination.

HTTP Request

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

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

{
  "data": [
    {
      "type": "script_job",
      "id": 331,
      "attributes": {
        "script_name": "Say Hi",
        "content": "#!/bin/bash \r\n\r\necho \"Hello!\"\r\n",
        "job_id": "826f0",
        "variable_support": false,
        "status": "pending",
        "pending_count": 2,
        "success_count": 1,
        "errored_count": 0,
        "created_by": "API (My API Key)",
        "created_at": "2022-05-31T11:56:05.043-07:00",
        "updated_at": "2022-06-01T10:19:38.816-07:00"
      },
      "relationships": {
        "device": {
          "data": [
            {
              "type": "device",
              "id": 33,
              "status": "pending"
            },
            {
              "type": "device",
              "id": 28,
              "status": "completed",
            },
            {
              "type": "device",
              "id": 17,
              "status": "pending"
            }
          ]
        }
      }
    }
  ],
  "has_more": true
}

Retrieve one

Retrieve details about a specific Script Job, including any results from the associated devices.

Possible values for the Script Job status are: pending, completed-with-errors, completed, and cancelled.

Possible values for the Device status are: completed, pending, error, and cancelled.

HTTP Request

GET https://a.simplemdm.com/api/v1/script_jobs/{SCRIPT_JOB_ID}

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

{
  "data": {
    "type": "script_job",
    "id": 331,
    "attributes": {
      "script_name": "Say Hi",
      "content": "#!/bin/bash \r\n\r\necho \"Hello!\"\r\n",
      "job_id": "826f0",
      "variable_support": false,
      "status": "pending",
      "pending_count": 2,
      "success_count": 1,
      "errored_count": 0,
      "created_by": "API (My API Key)",
      "created_at": "2022-05-31T11:56:05.043-07:00",
      "updated_at": "2022-06-01T10:19:38.816-07:00"
    },
    "relationships": {
      "device": {
        "data": [
          {
            "type": "device",
            "id": 33,
            "status": "pending",
            "status_code": null,
            "response": null
          },
          {
            "type": "device",
            "id": 28,
            "status": "completed",
            "status_code": "0",
            "response": "Hello!\n"
          },
          {
            "type": "device",
            "id": 17,
            "status": "pending",
            "status_code": null,
            "response": null
          }
        ]
      }
    }
  }
}

Create

Run a script on a collection of devices. Scripts are supported on macOS only.

HTTP Request

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

Argument Description
script_id Required. The ID of the script to be run on the devices
device_ids A comma separated list of device IDs to run the script on
group_ids A comma separated list of group IDs to run the script on. All macOS devices from these groups will be included.
assignment_group_ids A comma separated list of assignment group IDs to run the script on. All macOS devices from these assignment groups will be included.

At least one of device_ids, group_ids, or assignment_group_ids must be provided.

Refer to (Retrieve one)[#retrieve-one-10] for monitoring progress.

curl "https://a.simplemdm.com/api/v1/script_jobs" \
  -X POST \
  -u {API_KEY}: \
  -F script_id=35 \
  -F device_ids=1,2,3 \
  -F group_ids=4,5 \ 
  -F assignment_group_ids=6,7


{
  "data": {
    "type": "script_job",
    "id": 341,
    "attributes": {
      "script_name": "My Script",
      "content": "#!/bin/bash\necho \"Hello World!\"",
      "job_id": "87135",
      "variable_support": true,
      "status": "pending",
      "pending_count": 1,
      "success_count": 0,
      "errored_count": 0,
      "created_by": "API (Test API)",
      "created_at": "2022-06-01T11:26:10.505-07:00",
      "updated_at": "2022-06-01T11:26:10.505-07:00"
    },
    "relationships": {
      "device": {
        "data": [
          {
            "type": "device",
            "id": 33,
            "status": "pending",
            "status_code": null,
            "response": null
          }
        ]
      }
    }
  }
}

Cancel Job

You can use this method delete cancel a job. Jobs can only be canceled before the device has received the command.

HTTP Request

DELETE https://a.simplemdm.com/api/v1/script_jobs/{SCRIPT_ID}

curl "https://a.simplemdm.com/api/v1/script_jobs/341" \
  -X DELETE \

HTTP/1.1 204 No Content

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: