NAV
API version 1.50

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. These methods also support ordering the result set by specifying the direction parameter.

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.
direction Optional. The direction to sort the result set. Possible values are asc or desc. Defaults to asc.

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,
        "installation_channels": [
          "standard"
        ],
        "platform_support": "iOS",
        "processing_status": "processed"
      }
    },
    {
      "type": "app",
      "id": 63,
      "attributes": {
        "name": "Surf Report",
        "bundle_identifier": "com.portlandsurfclub.ent.surfreport2.2",
        "app_type": "enterprise",
        "version": "2.2",
        "installation_channels": [
          "standard"
        ],
        "platform_support": "iOS",
        "processing_status": "processed"
      }
    },
    {
      "type": "app",
      "id": 67,
      "attributes": {
        "name": "Scanner Pro",
        "app_type": "custom b2b",
        "itunes_store_id": 44827291,
        "installation_channels": [
          "standard"
        ],
        "platform_support": "iOS",
        "processing_status": "processed"
      }
    }
  ],
  "has_more": false
}

Supports pagination.

HTTP Request

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

Argument Description
include_shared If true, includes assigned apps from the shared catalog. Defaults to false.

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 or name of an existing app. Does not work for shared apps.

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

Update Munki Pkg Info

Upload a new XML or PLIST file for a Munki App.

HTTP Request

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

Argument Description
file Required. XML or PLIST file to replace any preexisting file. Send as multipart/form-data. 
curl https://a.simplemdm.com/api/v1/apps/{APP_ID}/munki_pkginfo \
  -X POST \
  -F [email protected] \
  -u ${API_KEY}:

HTTP/1.1 202 Accepted

Delete Munki Pkg Info

Delete Munki information.

HTTP Request

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

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

HTTP/1.1 204 No Content

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.
type Optional. Type of assignment group. Must be one of standard (for MDM app/media deployments) or munki for Munki app deployments. Defaults to standard.
install_type Optional. The install type for munki assignment groups. Must be one of managed or self_serve or managed_updates. This setting has no effect for non-munki (standard) assignment groups. Defaults to managed.

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": "[email protected]"
            }
        },
        {
            "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": "[email protected]"
      }
    }
}

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/{DEVICE_ID}/custom_attribute_values \
  -u ${API_KEY}:

{
  "data": [
    {
      "type": "custom_attribute_value",
      "id": "my_first_custom_attribute",
      "attributes": {
        "value": "hello",
        "secret": false,
        "source": "account"
      }
    },
    {
      "type": "custom_attribute_value",
      "id": "my_other_custom_attribute",
      "attributes": {
        "value": "",
        "secret": true,
        "source": "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. 
curl "https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/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}

Set multiple values for a device

Set multiple custom attribute values for a device.

Argument Description
[{"name": "my_custom_attribute_1", "value": "test1"}] Required. An array of json objects where each object contains a 'name' and 'value' key 
curl "https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/custom_attribute_values" \
  -u "${API_KEY}:" \
  -X "PUT" \
  -H 'Content-Type: application/json' \
  -d '{
  "data": [
        {
           "name": "my_custom_attribute_1",
           "value": "test1"
         },
         {
           "name": "my_custom_attribute_2",
           "value": "test2"
         }
      ]
  }'

HTTP Request

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

Set custom attribute value for multiple devices

Set the value for a custom attribute on multiple devices

Argument Description
[{"device_id": "123", "value": "test1"}] Required. An array of json objects where each object contains a 'device_id' and 'value' key 
curl "https://a.simplemdm.com/api/v1/custom_attribute_values/my_custom_attribute" \
  -u ${API_KEY}: \
  -X "PUT" \
  -H 'Content-Type: application/json' \
  -d '{
        "data": [
            {
              "device_id": "123",
              "value": "test1"
            },
            {
              "device_id": "321",
              "value": "test2"
            }
        ]
      }'

HTTP Request

PUT https://a.simplemdm.com/api/v1/custom_attribute_values/my_custom_attribute

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",
        "secret": false,
        "source": "group"
      }
    },
    {
      "type": "custom_attribute_value",
      "id": "my_other_custom_attribute",
      "attributes": {
        "value": "",
        "secret": true,
        "source": "account"
      }
    }
  ]
}

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

Argument Description
search Limit response to profiles with matching profile name 
curl https://a.simplemdm.com/api/v1/custom_configuration_profiles \
  -u ${API_KEY}:

{
    "data": [
        {
            "type": "custom_configuration_profile",
            "id": 293814,
            "attributes": {
                "name": "Munki Configuration",
                "reinstall_after_os_update": false,
                "profile_identifier": "com.unwiredmdm.aabc717175a3467b93af177aa5f1992d"
                "user_scope": true,
                "attribute_support": false,
                "escape_attributes": 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.
escape_attributes Optional. A boolean true or false. When enabled, SimpleMDM escape the values of the custom variables in the uploaded profile.
reinstall_after_os_update Optional. A boolean true or false. When enabled, SimpleMDM will re-install the profile automatically after macOS software updates are detected.

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.
escape_attributes Optional. A boolean true or false. When enabled, SimpleMDM escape the values of the custom variables in the uploaded profile.
reinstall_after_os_update Optional. A boolean true or false. When enabled, SimpleMDM will re-install the profile automatically after macOS software updates are detected.

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.
include_secret_custom_attributes When true, returns all custom attribute values including those marked as secret. 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": "2022-07-13T16:00:54.000-07:00",
        "last_seen_ip": "203.0.113.0",
        "enrolled_at": "2022-11-14T21:37:37.000-08:00",
        "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
          }
        },
        "custom_attribute_values" {
          "data": [
            {
              "type": "custom_attribute_value",
              "id": "custom_attribute_name",
              "attributes": {
                "secret": false,
                "value": "custom attribute value"
              }
            }
          ]
        }
      }
    },

    ...

  ],
  "has_more": false
}

HTTP Request

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

Retrieve one

Argument Description
include_secret_custom_attributes When true, returns all custom attribute values including those marked as secret. Defaults to false. 
curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID} \
  -u ${API_KEY}:

{
  "data": {
    "type": "device",
    "id": 121,
    "attributes": {
      "name": "Mike's iPhone",
      "last_seen_at": "2022-07-13T16:00:54.000-07:00",
      "last_seen_ip": "203.0.113.0",
      "enrolled_at": "2022-11-14T21:37:37.000-08:00",
      "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,
      "dep_enrolled": false,
      "dep_assigned": 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
          }
        },
        "custom_attribute_values" {
          "data": [
            {
              "type": "custom_attribute_value",
              "id": "custom_attribute_name",
              "attributes": {
                "secret": false,
                "value": "custom attribute value"
              }
            }
          ]
        }
      }
    }
  }
}

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/{DEVICE_ID} \
  -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/{DEVICE_ID} \
  -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/{DEVICE_ID}/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/{DEVICE_ID}/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/{DEVICE_ID}/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/{DEVICE_ID}/users/5 \
  -u ${API_KEY}:
  -X "DELETE"

HTTP/1.1 202 Accepted

Push assigned apps

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/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/{DEVICE_ID}/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/{DEVICE_ID}/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/{DEVICE_ID}/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/{DEVICE_ID}/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/{DEVICE_ID}/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/{DEVICE_ID}/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 firmware password

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/rotate_firmware_password \
  -u ${API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

You can use this method to rotate the firmware password for 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}/rotate_firmware_password

Clear recovery lock password

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/clear_recovery_lock_password \
  -u ${API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

You can use this method to remove the recovery lock password from a device. The recovery lock 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_recovery_lock_password

Rotate recovery lock password

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/rotate_recovery_lock_password \
  -u ${API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

You can use this method to rotate the recovery lock password for a device. The recovery lock 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}/rotate_recovery_lock_password

Rotate FileVault recovery key

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/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

Set Admin Password

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/set_admin_password \
  -u ${API_KEY}: \
  -d new_password=AReallyL0ngPasswordW1thNumberzAndSymbols \
  -X POST

HTTP/1.1 202 Accepted

You can use this method to set the macOS Auto Admin password for a mac device

HTTP Request

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

Argument Description
new_password Required

Rotate Admin Password

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/rotate_admin_password \
  -u ${API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

You can use this method to rotate the macOS Auto Admin password for a macOS device.

HTTP Request

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

Wipe

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/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/{DEVICE_ID}/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 tvOS, iOS and macOS devices.

HTTP Request

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

Argument Description
os_update_mode Required for macOS devices and disregarded for iOS. Possible values are 'smart_update', 'download_only', 'notify_only', 'install_asap', or 'force_update'.
version_type Possible values are 'latest_minor_version', 'latest_major_version'. Defaults to 'latest_major_version'.

Enable Remote Desktop

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/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/{DEVICE_ID}/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

Enable Bluetooth

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/bluetooth \
  -u ${API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

You can use this method to enable bluetooth on a device. Available in iOS 11.3 and later for supervised devices and in macOS 10.13.4 and later.

HTTP Request

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

Disable Bluetooth

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

HTTP/1.1 202 Accepted

You can use this method to disable bluetooth on a device. Available in iOS 11.3 and later for supervised devices and in macOS 10.13.4 and later.

HTTP Request

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

Set Time Zone

You can use this method to configure the local time zone setting on devices. Supported by iOS 14.0+ and tvOS 14.0+ devices only.

Argument Description
time_zone Required. TZ Identifier to be set on the device. 
curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/set_time_zone \
  -d time_zone="America/Denver" \
  -u ${API_KEY}: \
  -X POST

HTTP/1.1 204 No Content

HTTP Request

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

Unenroll

You can use this method to unenroll your device.

curl https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/unenroll \
  -u ${API_KEY}: \
  -X POST

HTTP/1.1 202 Accepted

HTTP Request

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

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

Enrollments provide a means of adding devices to your SimpleMDM account. This endpoint excludes enrollments that use automated methods such as those connected to Apple Business Manager, Apple School Manager. Enrollments with a device relationship represent One-time Enrollments. Account Driven enrollments have a null URL attribute.


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

{
  "data": [
    {
      "type": "enrollment",
      "id": 2,
      "attributes": {
        "url": "https://a.simplemdm.com/enroll/?c=12345678",
        "user_enrollment": false,
        "welcome_screen": true,
        "authentication": false
      },
      "relationships": {
        "device_group": {
          "data": {
            "type": "device_group",
            "id": 1
          }
        }
      }
    },
    {
      "type": "enrollment",
      "id": 3,
      "attributes": {
        "url": null,
        "user_enrollment": false,
        "welcome_screen": true,
        "authentication": false
      },
      "relationships": {
        "device_group": {
          "data": {
            "type": "device_group",
            "id": 1
          }
        }
      }
    },
    {
      "type": "enrollment",
      "id": 4,
      "attributes": {
        "url": "https://a.simplemdm.com/enroll/?c=87654321",
        "user_enrollment": false,
        "welcome_screen": false,
        "authentication": true
      },
      "relationships": {
        "device_group": {
          "data": {
            "type": "device_group",
            "id": 1
          }
        },
        "device": {
          "data": {
            "type": "device",
            "id": 2
          }
        }
      }
    },
    {
      "type": "enrollment",
      "id": 7,
      "attributes": {
        "url": "https://a.simplemdm.com/enroll/?c=09876543",
        "user_enrollment": false,
        "welcome_screen": false,
        "authentication": false
      },
      "relationships": {
        "device_group": {
          "data": {
            "type": "device_group",
            "id": 1
          }
        },
        "device": {
          "data": {
            "type": "device",
            "id": 4
          }
        }
      }
    }
  ],
  "has_more": true
}

Supports pagination.

HTTP Request

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

Retrieve One

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

{
  "type": "enrollment",
  "id": 2,
  "attributes": {
    "url": "https://a.simplemdm.com/enroll/?c=12345678",
    "user_enrollment": false,
    "welcome_screen": true,
    "authentication": false
  },
  "relationships": {
    "device_group": {
      "data": {
        "type": "device_group",
        "id": 1
      }
    }
  }
}

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. The invitation will contain a link to enroll the device. This endpoint does not support Account Driven enrollments.

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

curl https://a.simplemdm.com/api/v1/enrollments/2/invitiations \
  -u ${API_KEY}: \
  -X POST \
  -d "[email protected]"

HTTP/1.1 200 Success

Delete

Delete an enrollment from your account.

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

HTTP/1.1 204 No Content

HTTP Request

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

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": "[email protected]"
            }
          }
        }
      }
    }
  ],
  "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

Profiles

List all

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

Argument Description
search Limit response to profiles with matching profile name or type 
curl https://a.simplemdm.com/api/v1/profiles \
  -u ${API_KEY}:

{
  "data": [
    {
      "type": "apn",
      "id": 145593,
      "attributes": {
        "name": "APN",
        "profile_identifier": "com.unwiredmdm.5d91d2df438d4e51b4e1efa9a6f18bdb",
        "user_scope": true,
        "group_count": 0,
        "reinstall_after_os_update": false,
        "device_count": 1
      }
    },
    {
      "type": "app_restrictions",
      "id": 145594,
      "attributes": {
        "name": "App Restriction",
        "profile_identifier": "com.unwiredmdm.c87dce2487464c19a683263907978cf7",
        "user_scope": false,
        "group_count": 1,
        "device_count": 1
      }
    }
  ],
  "has_more": false
}

HTTP Request

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

Retrieve one

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

{
  "data": {
    "type": "email",
    "id": 145693,
    "attributes": {
      "name": "Email Account",
      "profile_identifier": "com.unwiredmdm.f3d2b23b577141eca55d813858daca3d",
      "user_scope": false,
      "group_count": 0,
      "reinstall_after_os_update": false,
      "device_count": 0
    },
    "relationships": {
      "device_groups": {
        "data": []
      }
    }
  }
}

HTTP Request

GET https://a.simplemdm.com/api/v1/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/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/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/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/profiles/{PROFILE_ID}/devices/{DEVICE_ID}

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": "[email protected]",
            "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 [email protected] \
  -F apple_id=[email protected] \
  -u ${API_KEY}:

{
    "data": {
        "type": "push_certificate",
        "attributes": {
            "apple_id": "[email protected]",
            "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": 663,
      "attributes": {
        "script_name": "Touch files",
        "job_name": "API Job",
        "content": "#!/bin/bash \r\n\r\necho \"Hello!\"\r\n",
        "job_id": "9ca35",
        "variable_support": false,
        "status": "pending",
        "pending_count": 1,
        "success_count": 0,
        "errored_count": 0,
        "custom_attribute_regex": "\n",
        "created_by": "API (Test API)",
        "created_at": "2023-06-22T15:06:21.910-07:00",
        "updated_at": "2023-06-22T15:06:21.910-07:00"
      },
      "relationships": {
        "device": {
          "data": [
            {
              "type": "device",
              "id": 17,
              "status": "pending"
            }
          ]
        },
        "custom_attribute": {
          "data": {
            "type": "custom_attribute",
            "id": "greeting_attribute"
          }
        }
      }
    }
  ],
  "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,
      "custom_attribute_regex": "\n",
      "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
          }
        ]
      },
      "custom_attribute": {
        "data": {
          "type": "custom_attribute",
          "id": "greeting_attribute"
        }
      }
    }
  }
}

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.
custom_attribute Optional. If provided the output from the script will be stored in this custom attribute on each device.
custom_attribute_regex Optional. Used to sanitize the output from the script before storing it in the custom attribute. Can be left empty but \n is recommended.

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

Refer to Retrieve one 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 \
  -F custom_attribute=greeting_attribute \
  -F "custom_attribute_regex=\\n"


{
  "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,
      "custom_attribute_regex": "\n",
      "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
          }
        ]
      },
      "custom_attribute": {
        "data": {
          "type": "custom_attribute",
          "id": "greeting_attribute"
        }
      }
    }
  }
}

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: