Commonly Used APIs – Esper Help

In this article, you’ll find a list of common APIs used by our customers and our own team. For a more exhaustive list, the Esper API Docs contains a list of all of our APIs. If you’re new to APIs, you may want to start our Getting Started with APIs guide and then return here.

In this article:

APIs for Finding IDs
Useful Device Actions
Device Commands
Managing Files
Managing Applications

APIs for Finding IDs

The following APIs are useful for gathering IDs. As a best practice, we've append the parameter ?limit=25 to each URI. To pull the next 25 objects, append the parameter ?limit=25&offset=25.

Get all Devices

The Get All Devices API is useful for interacting with your devices programmatically.

GET https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/device/?limit=25

Useful Payload Data

Key	Data Type	Explanation
`id`	String	The device ID (not to be confused with the device’s console name) that can be used to interact with other APIs.
`deviceName`	String	The device’s display name in the Esper Console.
`androidVersion`	String	The device's Android version.

Get All Groups

The Get All Groups API returns group IDs that can be used in other APIs.

GET
https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/devicegroup/?limit=25

Get All Apps

Returns the IDs for all Apps enabled in a tenant, as well as other app information.

GET https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/application/?limit=25

Useful Device Actions

Get Device Info

Find information about the device. It returns information such as software and hardware specs and Wi-Fi information (not including passwords).

GET https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/device/{device_id}/

Sample Response


    {
    "id": "d0c5e04b-6506-422b-882f-dc48b9b9028b",
    "url": "https://sample-api.esper.cloud/api/enterprise/4212ac3a-824f-48d9-bd84-7867092f3cba/device/18a787cc-1cfc-4cab-af68-8501773554b7/",
    "device_name": "ESP-SAMP-AAA11",
    "policy_name": null,
    "status": 1,
    "current_command": null,
    "memoryInfo": {
        "totalRam": "1849",
        "totalInternalStorage": "16000",
        "internalStorageBinaryPrefix": false
    },
    "displays": {
        "name": "Built-in Screen",
        "width": 800,
        "height": 1280,
        "density": 1.5,
        "displayId": 0,
        "refreshRate": 60.0
    },
    "softwareInfo": {
        "supportedAbi": "arm64-v8a",
        "androidVersion": "10",
        "androidBuildTime": 1680222503000,
        "bootloaderVersion": "unknown",
        "androidBuildNumber": "TB-8505F_S300907_230331_BMP",
        "securityPatchLevel": "2023-02-05",
        "deviceKernelVersion": "4.9.190+",
        "foundationInfo": null,
        "isSupervisorPluginActive": true,
        "isKnoxActive": false,
        "isCSDKActive": false
    },
    "hardwareInfo": {
        "brand": "Lenovo",
        "model": "Lenovo TB-8505F",
        "hardware": "mt8766",
        "manufacturer": "LENOVO",
        "serialNumber": "A1A1A1"
    },
    "networkInfo": {
        "imei1": null,
        "imei2": null,
        "wifiMacAddress": "00:00:00:00:00:00",
        "ethernetMacAddress": null,
        "iccid1": null,
        "iccid2": null,
        "phoneNumber1": null,
        "phoneNumber2": null
    },
    "audioConstraints": null,
    "dpcInfo": null,
    "template_name": "Sample",
    "mqtt_id": "/3584426c-1d30-419e-9be9-3b2ff8bc6672/f579841c-64bb-4342-a6cb-e8d1dc16e28a/",
    "iot_mqtt_base_topic": "iot/EpserStagingNvrg/sample/3584426c-1d30-419e-9be9-3b2ff8bc6672/f579841c-64bb-4342-a6cb-e8d1dc16e28a/",
    "state": 1,
    "suid": "7c858dd8-17c3-4a2d-9c82-d53a5f9552af",
    "fcm_id": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1",
    "api_level": 29,
    "created_on": "2022-12-05T21:13:01.205516Z",
    "updated_on": "2023-08-21T22:38:19.293874Z",
    "is_active": true,
    "provisioned_on": "2023-08-21T22:32:41.690343Z",
    "is_gms": true,
    "esper_client": "v7.12.4258",
    "enterprise": "https://sample-api.esper.cloud/api/enterprise/3584426c-1d30-419e-9be9-3b2ff8bc6672/",
    "policy": null,
    "user": "https://sample-api.esper.cloud/api/user/849/",
    "groups": [
        "https://sample-api.esper.cloud/api/enterprise/3584426c-1d30-419e-9be9-3b2ff8bc6672/devicegroup/18a787cc-1cfc-4cab-af68-8501773554b7/"
    ],
    "tags": null,
    "use_mqtt": true,
    "use_iot_mqtt": false,
    "alias_name": null,
    "device_type": "real",
    "current_app_mode": 1,
    "lockdown_state": 1,
    "timezone_string": "America/New_York",
    "wifi_access_points": [
        {
            "id": "78af65a5-adf0-49df-b6b9-23d45fefcc45",
            "wifi_ssid": "Esper",
            "wifi_security_type": "SAE",
            "wifi_phase2_auth": "NONE",
            "config_style": "MANUAL",
            "wifi_eap_method": "NONE",
            "identity": "",
            "anonymous_identity": "",
            "domain": "",
            "hidden": false,
            "wifi_password": null,
            "status_id": null
        },
        {
            "id": "fa8c814d-637f-497f-a935-aab1732568cf",
            "wifi_ssid": "Esper_Devices",
            "wifi_security_type": "SAE",
            "wifi_phase2_auth": "NONE",
            "config_style": "MANUAL",
            "wifi_eap_method": "NONE",
            "identity": "",
            "anonymous_identity": "",
            "domain": "",
            "hidden": false,
            "wifi_password": null,
            "status_id": null
        }
    ],
    "managed_by": "TEMPLATE",
    "has_seamlessInfo": false,
    "emm_device": null,
    "assigned_blueprint_id": "N/A",
    "current_blueprint_id": "N/A",
    "current_blueprint_version_id": "N/A",
    "current_blueprint_version_number": "N/A",
    "provisioned_with": "TEMPLATE",
    "blueprint_upgrade_status": "UPGRADABLE",
    "initialtemplate": "https://sample-api.esper.cloud/api/enterprise/3584426c-1d30-419e-9be9-3b2ff8bc6672/device/18a787cc-1cfc-4cab-af68-8501773554b7/initialtemplate/",
    "kiosk_app_name": null
}

Move Devices to a Group

Need to move devices from one Group to another? Use this API to move devices into a different Group. You’ll need the device_ids from Get All Devices and the group_id from Get All Groups. Devices may only be moved to one Group at a time.

API

PATCH https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/devicegroup/{devicegroup_id}/?action=add

Body

{ 
 "devices": [
   "device_id"
 ]
}

Get Latest Device Event

Need to check on a device that recently went missing? Use this API to retrieve information about its last known location and the last time it communicated with the Esper cloud.

The latest event also has information on the device's telemetry data such as sensors, location, wi-fi, battery temperature, and more.

Device API

GET https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/device/{device_id}/status/?latest_event=1

Group API

GET https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/group/{group_id}/download/eventfeed/

Get Command List

See a list of the commands issued to the device, the user who issued the command, and the status of the command.

API

GET  https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/device/{device_id}/download/eventfeed/

Device Commands

A variety of commands may be sent to a device through the request body. In the list below, we’ve listed the most popular ones. See a full list of commands.

For most of these APIs, you can replace

 "devices": [
        "device_id"
    ]

with

 "groups": [
        "group_id"
    ]

to send the command to Groups instead of devices. Separate each ID with a comma.

Ping a Device

Also known as “Get Device Heartbeat”, the Update Heartbeat command pings a device or Group. It also returns information such as the Group the device is in, if any.

API

POST 
https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Body

{
   "command_type": "DEVICE",
   "devices": [
       "device_id"
   ],
   "device_type": "all",
   "command": "UPDATE_HEARTBEAT"
}

Broadcast a Message to a Device

Send a daily reminder to device users informing them that tablets will be wiped after each day. Or, notify your end users that they’ll receive an update soon. To broadcast a message to your devices, use the Command Notify Device API:

API

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Key	Data Type	Explanation
`title`	String	The title of the message.
`message`	String	The message.
`url`	String	Optional. A URL which once tapped will redirect the user to a website. A link button will appear. The user may tap this option and be redirected to a website.

Immediate Scheduled Window

Send a command to a device immediately.

Body

{
   "command_type": "DEVICE",
   "command": "NOTIFY_DEVICE",
   "command_args": {
       "title": "title",
       "message": "message.",
       "url": "optional_url"
   },
   "devices": [
       "device_id"
   ],
   "device_type": "all"
}

To schedule a notification, include the following in the body of the request.

Key	Data Type	Explanation
`title`	String	The title of the message.
`message`	String	The message.
`url`	String	A URL which once tapped will redirect the user to a website. A link button will appear. The user may tap this option and be redirected to a website.
`schedule`	String	Choose to send the message immediately or over a scheduled window. If window is used, the “schedule_args” are required.
`name`	String	Name of the scheduled command.
`start_datetime`	String	The start date for the schedule. Must be before end_datetime with a difference of at least three minutes. Example: "2023-04-25T17:15:22Z”.
`end_datetime`	String	The end date for the schedule. Must be after start_datetime with a difference of at least three minutes. Example: "2023-04-26T17:20:22Z".
`time_type`	String	Choose between Console time or device time.
`devices`	String	The device IDs.

{
   "command_type": "DEVICE",
   "command": "NOTIFY_DEVICE",
   "command_args": {
       "title": "title",
       "message":"message",
       "url":"optional_url"
   },
   "schedule": "WINDOW",
   "schedule_args": {
       "start_datetime": "start_datetime",
       "end_datetime": "end_datetime",
       "time_type": "console",
     },
   "devices": [
       "device_id"
   ],
   "device_type": "all"
}

Example of the message on a device.

Without URL

With URL

When including a URL, a browser must be in the Show state.

Reset PIN for Lock Screen

Was the lockscreen PIN changed for your devices? Set this command to change it to your preferred PIN.

Note: This command may not work on all devices.

API

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Body

{
 "command_type": "DEVICE",
 "devices": [
   "device_id"
 ],
 "command": "RESET_LOCKSCREEN_PASSWORD",
 "command_args": {
   "new_lockscreen_password": "new_lockscreen_password"
  }
}

Enable adb

Need to enable or disable adb? Set the adb_state to ENABLE or DISABLED. You may need to agree to the notification on the device.

API

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Body

{
    "command_type": "DEVICE",
    "device_type": "all",
    "devices": [
        "device-id"
    ],
    "command": "SET_ADB_STATE",
    "command_args": {
        "adb_state": "ENABLED"
    }
}

Managing Files

These APIs allows you to manage files. To upload a file and push it to devices, you’ll need the following:

The file should be uploaded to the Content Management section in the Esper Console
The Device IDs (from Get All Devices)
The File Name and ID (from Get All Files)

Upload a File to Esper

To push a file to a device or Group, you’ll need to first upload that file to the Esper Cloud. You can do this via the Console, or through the API.

API

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/content/upload/

Body

Body type: Form Data
Body Key: key
Body Value: {file}

In Postman

In Postman, after inputting the API and POST request, in the Body tab, select form-data. Then input “key” in the Key field. Hover over the Key field until the “Text” dropdown menu appears. Select File from the dropdown.

file

The Value field will then display a Select Files button. Select the file you wish to upload.

select

Get All Files

After uploading a file to the Esper Console, find its ID with this API. Files are uploaded to the Content Management section in the Esper Console.

GET  https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/content/

Response

If you are pushing a file to a Device or Group, take note of the app’s id and name in the response.

Push File to Device or Group

After uploading a file and finding its name and ID, you can push that file to Devices or Groups.

API

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Body

The id and ui_content_name can be obtained from the Get All Files API.

Key	Data Type	Explanation
`content_id`	String	The `id` as it appears in the Get All Files response.
`ui_content_name`	String	The `name` as it appears in the Get All Files response.
`content_destination_path`	String	The path the file will be saved to. If a folder does not exist in that location, one will be created. May require device-level permissions. Example: `/storage/emulated/0/download`
`content_destination_type`	String	external
`device_id`	String	The device IDs (found in Get All Devices).

Body

{
    "command_type": "DEVICE",
    "command_args": {
        "kind": "DOWNLOAD_CONTENT",
        "content_id": "content_id",
        "content_destination_path": "dest_path",
        "content_destination_type": "external",
        "ui_content_name": "file_name"
    },
    "devices": [
        "device_id"
    ],
    "device_type": "all",
    "command": "SYNC_CONTENT"
}

Managing Applications

Get App Info

Use the top-level ID (not the version ID) to find information about an app in the Esper Cloud.

API

GET
https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/application/{application_id}/

Get All Apps Installed on a Device

Get a list of all apps on a device.

API

GET https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/device/{device_id}/app/

Upload an App to the Esper Cloud

Upload an app to the Esper Cloud.

API

POST https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/application/upload/

Body

Body type: Form Data
Body Key: app_file
Body Value: {file}

In Postman

In Postman, in the Body, select form-data. Then use app_file as the Key.

Hover over the Key field. A Text option should appear. Click on the Text option to select File.

Click on the Select Files button and browse for the app. select

Install an Application to Devices

Install an application to devices.

To retrieve the required and optional app information, see Get App Info.

API

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Body

{
    "command_type": "DEVICE",
    "command_args": {
        "app_version": "app_version_id_required",
        "application_name": "app_name_optional",
        "package_name": "package_name_required",
        "version_code": "version_code_optional",
        "version_name": "version_name_optional",
        "is_g_play": true
    },
    "devices": [
        "device_id"
    ],
    "device_type": "all",
    "command": "INSTALL"
}

Launch an App on Devices

Launch an app on devices.

API

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Body

Intent Action: The package name

Component Name: The package activity

For example, if we wanted to launch the Esper Settings app, we would use:

Intent Action: io.shoonya.shoonyadpc
Component Name: io.shoonya.shoonyadpc/com.shoonyaos.shoonyasettings.activities.MainActivity

{
    "command_type": "DEVICE",
    "command": "UPDATE_DEVICE_CONFIG",
    "command_args": {
        "custom_settings_config": {
            "scripts": [
                {
                    "action": "LAUNCH",
                    "actionParams": {
                        "intentAction": "package_name",
                        "componentName": "package_name/.activity_name",
                        "flags": 268435456
                    }
                }
            ]
        }
    },
    "devices": [
        "device_id"
    ],
    "device_type": "all"
}

This uses the New Activity Android Intent flag. Read more about using Android Intent flags.

Manage your device fleet with APIs and take control of devices at scale!

APIs for Finding IDs

Get all Devices

Get All Groups

Get All Apps

Useful Device Actions

Get Device Info

Move Devices to a Group

Get Latest Device Event

Get Command List

Device Commands

Ping a Device

Broadcast a Message to a Device

Reset PIN for Lock Screen

Enable adb

Managing Files

Upload a File to Esper

Get All Files

Push File to Device or Group

Managing Applications

Get App Info

Get All Apps Installed on a Device

Upload an App to the Esper Cloud

Install an Application to Devices

Launch an App on Devices

Related articles

Featured content