Skip to content

ESPER API REFERENCE (1.0.0)

Introduction

Welcome to Esper’s API documentation. The Esper API allows users to accomplish operations outside of the console. Some common uses for our APIs include observing device information and console activity, installing and updating apps, uploading files, and sending files to devices. Our users have also used the API to automate app updates, perform bulk actions, and more.

Esper API endpoints use REST-based architecture and return JSON responses.

See our documentation for:

Authentication

You need to create an API Key to interact with our APIs. Learn more about generating an API Key. You can also learn more about Esper and sign up for an account at esper.io/signup.

Some endpoints also require an Enterprise ID. This ID can be found in the API Management section of the Esper console.

Pagination

Responses may be paginated. Use the following parameters to query the data. A full list of parameters can be found on the endpoint’s documentation page.

ParameterData TypeExplanation
limitintegerLimit the data returned. Default = 20.
offsetintegerOffset to the first item returned. Default = 0.
orderingstringOrder the results set by the field name. Varies by endpoint.
nextstringPaginate to the next response set.
previousstringPaginate to the last set response.

Errors

We use standard HTTP status codes for success or failure. A typical error response may look something like this:

{
  "errors": [],
  "message": "error message",
  "status": 400
}
  • errors - List of error details
  • message - Error description
  • status - HTTP status code

Some common status codes and messages are:

NumberMessageExplanation
200OKThe request succeeded.
201Resource creationA resource was created.
401UnauthorizedThe API key is invalid.
404Not foundThe resource was not found.
429Rate limit exceededToo many requests. Wait a moment and try again.
500Server errorInternal error. Wait a moment and try again. If the issue persists, contact Esper.

See how our systems are doing by checking our status page.

Rate Limits

To ensure quality of service for all customers, we enforce rate limits for API requests. Most customers won’t hit this limit with normal use. In case you experience 429 or rate limit exceeded errors, we recommend the following:

  • Try sending requests in batches.
  • Begin with about 20 requests at a time and building up from there.
  • Ensure your scripts are efficient and don’t contain redundant calls.
  • Reach out to your account manager to discuss your options.
Download OpenAPI description
Languages
Servers
Mock server
https://api.esper.io/_mock/openapi
https://{foo}-api.esper.cloud/api

Company Settings

Operations

Application

Operations

Application V1

Operations

AndroidDevice

Operations

Device Group

Operations

Token (Deprecated)

Operations

Commands V2

Operations

Enterprise Policy

Operations

Geofence

Operations

Content

Operations

User (Deprecated)

Operations

User

Operations

Blueprint (Deprecated)

Operations

Directory Record

Operations

Tile Icon

Operations

Alerts

Operations

Alarms

Operations

Wallpapers

Operations

Device Telemetry

Operations

Daily and Custom Reports

Operations

SSO Connections

Operations

Roles

Operations

Personal Access Token

Operations

Blueprints API

Operations

Custom Actions API

Operations

System

Operations

Pipelines

Operations

Stages

Operations

Target Lists

Operations

Targets

Operations

Device Groups

Operations

Operation Lists

Operations

Operations

Operations

Pipeline Runs

Operations

Stage Runs

Operations

Target Runs

Operations

Device

Operations

Device Heartbeat

Operations

Device Apps

Operations

Device Enrollment in EMM

Operations

Operations

Operations

DeviceOperations

Operations

MultiOS Remote Viewer

Operations

Device V2

Operations

VPP License Management

Operations

VPP App Management

Operations

Tenant Apps

Operations

Apple App Store

Operations

App List

Operations

Webclips

Operations

Provisioning Profiles

Operations

Esper Apps

Operations

Tenant Esper Apps

Operations

Command Request

Operations

Create a command request

Request

API to create a command request for a set of devices or groups. Works for mixed-fleet devices (Android, iOS, etc.) if the command is supported.

You can send the command immediately or schedule command for supported devices.

Scheduled commands are currently compatible with Android devices.

Security
apiKey
Bodyapplication/jsonrequired
command_typestring

Identifies the type of command

* DEVICE: command request is meant for devices
* GROUP: command request is meant for groups
* DYNAMIC: command request is meant for dynamic set of devices
  i.e subset of devices from different groups or otherwise.
Enum"DEVICE""GROUP""DYNAMIC"
aliasstring

Another name for the command, provided by the user or Console.

devicesArray of strings(uuid)[ 0 .. 1000 ] items

List of devices to run commands. Required if command_type is 'DEVICE' or 'DYNAMIC'

groupsArray of strings(uuid)[ 0 .. 500 ] items

List of groups to run commands. Required if command_type is 'GROUP' or 'DYNAMIC'

device_typestring

Filtering by device_type is currently not supported. Please specify 'all'.

Value"all"
commandstring(DeviceCommandEnum)

Following commands are supported

* ADD_TO_WHITELIST: Whitelist an installed sytem app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper
* ADD_WIFI_AP : Add wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points
* APPLY_APP_CONFIG : Apply app configuration for an installed app.
* CLEAR_APP_DATA : Clear data for an installed app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper
* CONVERGE: Converge command for Blueprint
* INSTALL: Install an app on a device. Requires `app_version` in command arguments where `app_version` is the version id of app uploaded on Esper
* INSTALL_CERTIFICATE: Install a certificate chain in the system keystore of an android device. Requires `cert_file_type`, `cert_data_base64`, `cert_alias_name` and `cert_storage_type` in command arguments where `cert_file_type` must be set to "pkcs12", `cert_data_base64` contains the base64 encoded content of the pkcs12 file, `cert_alias_name` is the alias name with which the certificate chain is supposed to be installed and `cert_storage_type` must be set to "system". If the pkcs12 file is password protected, the password should be specified in the optional parameter `cert_password`.
* LOCK: Lock device screen, Supports Android, iOS and Windows devices.
* REBOOT: Reboot a device. Supports Android, iOS, and Windows devices.
* REMOVE_FROM_WHITELIST : Remove an installed system app from whitelist. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper
* REMOVE_WIFI_AP : Remove Wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points
* SET_APP_PERMISSION : Set permission for an installed app. Requires `package_name`, `grant_state`, `permission` in command arguments where `package_name` is the app package uploaded on Esper, `grant_state` should be "PERMISSION_GRANT_STATE_DEFAULT", "PERMISSION_GRANT_STATE_DENIED", "PERMISSION_GRANT_STATE_GRANTED" and `permission` is a valid permission
* SET_APP_STATE : Set the state of an app - SHOW/HIDE/DISABLE/LAUNCHABLE_BUT_HIDDEN. Requries `app_state` and `package_name` in command arguments where `app_state` is the state of app and `package_name` is the app package uploaded on Esper For LAUNCHABLE_BUT_HIDDEN: Hide an app on the home screen but allow it to be launched from other apps. Requires Esper agent 8.5+ and `package_name`. 
* SET_BLUETOOTH_STATE : Set bluetooth state (ON/OFF) for device. Requires `bluetooth_state` in command arguments where `bluetooth_state` is a boolean.
* SET_BRIGHTNESS_SCALE : Set brightness for device. Requires `brightness_value` in command arguments where `brightness_value` is an integer (1-100).
* SET_DEVICE_LOCKDOWN_STATE : Set lockdown state for a device. Requires `state` and `message` in command arguments where `state` is LOCKED/UNLOCKED and `message` is the message to be added with command
* SET_GPS_STATE :Set the GPS state for a device. Requires `gps_state` in command arguments where `gps_state` should be either 0, 1, 2, 3 or 4 (LOCATION_MODE_HIGH_ACCURACY = 0, LOCATION_MODE_SENSORS_ONLY = 1, LOCATION_MODE_BATTERY_SAVING = 2, LOCATION_MODE_OFF = 3, LOCATION_MODE_ON = 4)
* SET_KIOSK_APP : Command to set the Kiosk app for a device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper

* SET_MULTI_APP_MODE : Command to set the device back to multi app mode.
* SET_NEW_POLICY : Apply policy on device. Requires `policy_url` in command arguments where `policy_url` is the URL to the policy
* SET_ROTATION_STATE : Set screen orientation. Requires `rotate_state` in command arguments where `rotate_state` should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)
* SET_SCREEN_OFF_TIMEOUT: Set screen off timeout for a device. Requires `screen_off_timeout` in command arguments where `screen_off_timeout` should be either -1 or between 5000 and 1800000
* SET_STREAM_VOLUME : Set strema volume for a device. Requires `stream` and `volume_level` in command arguments where `stream` should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music) and `volume_level` should be a value from 0 to 100
* SET_TIMEZONE : Set the timezone for a device. Requires `timezone_string` in command arguments where `timezone_string` is a valid string representing the timezone
* SET_WIFI_STATE : Set the wifi state (ON/OFF) for a device. Requires `wifi_state` in command arguments where `wifi_state` is a boolean.
* UNINSTALL: Uninstall an app from device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper
* UNINSTALL_CERTIFICATE: Uninstall a certificate from an android device's system keystore using the installed certificate's alias name. Requires `cert_alias_name` and `cert_storage_type` in command arguments where `cert_alias_name` is the alias name of the certificate to be uninstalled and `cert_storage_type` must be set to "system"
* UPDATE_DEVICE_CONFIG: Push additional configurations to the Device
* UPDATE_HEARTBEAT: Ping a device
* UPDATE_LATEST_DPC : Prompt device to update the DPC app to the latest versions.
* WIPE : Wipes the device.
* RESET_LOCKSCREEN_PASSWORD: Change the lockscreen password of the device. Requires `new_lockscreen_password` in command arguments where `new_lockscreen_password` is a valid string.
* UPDATE_BLUEPRINT: Pushes or reapplies the most current Blueprint version to the device or group.
* NOTIFY_DEVICE: Allows you to  broadcast message to the device.
* SET_DEVICE_LANGUAGE: Set language for a device. Requires locale value in xx[_Zzzz]_yy where xx is language code, Zzzz is script (optional) and yy is country code.
* SET_ETHERNET_SETTINGS: Set ethernet settings on supported Device
* SET_STATIC_IP: Set static ip on the deivce. Requires interface, dhcp_dnabled, static_ip, primary_dns, subnet_mask, gateway, secondary_dns (optional)
* BEEP_DEVICE: Allows you to make the device beep for a specified duration
* SET_APP_NOTIFICATIONS: Enable/disable app notifications. Requries `app_notifications_state` and `package_name` in command arguments where `app_notifications_state` is a string that has the value `ENABLED` or `DISABLED` and `package_name` is the app package uploaded on Esper.
* USE_ONLY_SAVED_WIFI_AP: Allow/disallow device to connect to unregistered WiFi APs. Requires boolean `use_only_saved_ap`..
* DEVICE_INFORMATION: Prompt device to update the device information
* VPP_APP_INSTALL: Install a vpp app on an iOS device. Requires `app_id` and `bundle_identifier` in command arguments that corresponds to the associate vpp app
* APPLE_APP_UNINSTALL: Uninstall an app on an iOS device. Requires `app_id` and `bundle_identifier` in command arguments that corresponds to the associated app
* CLEAR_PASSCODE: Clear the passcode in a device
* LIST_INSTALLED_PROFILES: Returns a list of all installed profiles on an iOS device.
* INSTALL_PROFILE: Install a profile on an iOS device.
* REMOVE_PROFILE: Remove a profile from an iOS device.
* RUN_SHELL_SCRIPT: Run a shell script on a Linux or Windows device. Requires `script` and `interpreter` in command arguments.
* RUN_CUSTOM_ACTION: Run a custom action (script) on a Linux device. Requires custom action parameters in command arguments.
* COLLECT_LOGS: Collect and upload Esper agent logs from a Linux device.
Enum"ADD_TO_WHITELIST""ADD_WIFI_AP""APPLY_APP_CONFIG""CLEAR_APP_DATA""CONVERGE""INSTALL""INSTALL_CERTIFICATE""LIST_INSTALLED_PROFILES""LOCK""REBOOT"
command_argsobject(Command args)
schedulestring(CommandScheduleEnum)

Following Schedule types are supported

* IMMEDIATE: Schedule the command to execcute Immediately
* WINDOW: Schedule the command to execute within the given window
* RECURRING: Schedule the command to execute during the scheduled time until it succeeds or expires. After executing successfully, it will not fire again.
Enum"IMMEDIATE""WINDOW""RECURRING"
schedule_argsobject(Command Schedule Arguments)
curl -i -X POST \
  https://api.esper.io/_mock/openapi/commands/v0/commands/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "command_type": "DEVICE",
    "alias": "string",
    "devices": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "groups": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "device_type": "all",
    "command": "ADD_TO_WHITELIST",
    "command_args": {
      "device_alias_name": "string",
      "custom_settings_config": {},
      "app_version": "string",
      "package_name": "string",
      "policy_url": "string",
      "wifi_access_points": {},
      "state": "string",
      "message": "string",
      "title": "string",
      "url": "string",
      "app_state": "string",
      "bluetooth_state": true,
      "brightness_value": 0,
      "gps_state": 0,
      "rotate_state": 0,
      "screen_off_timeout": 0,
      "stream": 0,
      "volume_level": 0,
      "timezone_string": 0,
      "wifi_state": true,
      "wifi_revert_timeout": 0,
      "locale": "string",
      "ethernet_auth_mode": "NONE",
      "ethernet_ca_cert_alias": "string",
      "ethernet_client_cert_alias": "string",
      "ethernet_eap_identity": "string",
      "interface": "string",
      "dhcp_enabled": "string",
      "static_ip": "string",
      "primary_dns": "string",
      "subnet_mask": "string",
      "secondary_dns": "string",
      "gateway": "string",
      "duration": "string",
      "video_quality": "HIGH",
      "enable_debug_mode": false,
      "app_id": "string",
      "bundle_identifier": "string",
      "managed_only": true,
      "profile_identifier": "string",
      "profile": "string",
      "is_converge": true,
      "script": "string",
      "interpreter": "string",
      "execute_as": "string",
      "cert_file_type": "string",
      "cert_data_base64": "string",
      "cert_alias_name": "string",
      "cert_storage_type": "string",
      "cert_password": "string",
      "is_factory_reset": true
    },
    "schedule": "IMMEDIATE",
    "schedule_args": {
      "name": "string",
      "start_datetime": "2019-08-24T14:15:22Z",
      "end_datetime": "2019-08-24T14:15:22Z",
      "time_type": "console",
      "window_start_time": "string",
      "window_end_time": "string",
      "days": [
        "string"
      ]
    }
  }'

Responses

Command request successfully created.

Bodyapplication/json
codeinteger
messagestring
contentobject(CommandRequest)
Response
application/json
{ "code": 0, "message": "string", "content": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "command_type": "DEVICE", "devices": [ … ], "groups": [ … ], "device_type": "active", "command": "ADD_TO_WHITELIST", "command_args": { … }, "schedule": "IMMEDIATE", "schedule_args": { … }, "reason": "string", "created_by": "string", "created_at": "2019-08-24T14:15:22Z" } }

Get a command request

Request

API to get a command request

Security
apiKey
Path
idstringrequired

ID of the command request object

curl -i -X GET \
  'https://api.esper.io/_mock/openapi/commands/v0/commands/{id}/' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Command request information

Bodyapplication/json
codeinteger
messagestring
contentobject(CommandRequest)
Response
application/json
{ "code": 0, "message": "string", "content": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "command_type": "DEVICE", "devices": [ … ], "groups": [ … ], "device_type": "active", "command": "ADD_TO_WHITELIST", "command_args": { … }, "schedule": "IMMEDIATE", "schedule_args": { … }, "reason": "string", "created_by": "string", "created_at": "2019-08-24T14:15:22Z" } }

Get stats of a command request

Request

API to get a aggregrated status for a command request

Security
apiKey
Path
idstringrequired

ID of the command request object

curl -i -X GET \
  'https://api.esper.io/_mock/openapi/commands/v0/commands/{id}/stats/' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Aggregrated status information for a command request.

Bodyapplication/json
codeinteger
messagestring
contentobject(CommandRequestStats)
Response
application/json
{ "code": 0, "message": "string", "content": { "id": "string", "status": [ … ] } }

Command Status

Operations

Converge

Operations

Converge Command

Operations

DEP Sync Request

Operations

ABM Provisioning

Operations

APNs certificate

Operations

DEP Tokens

Operations

VPP Token Management

Operations

Google Enterprise

Operations

FoundryBuilds

Operations

FoundryDeviceModels

Operations

FoundryEvents

Operations

Reports API

Operations

Query API

Operations

Ingest API

Operations