Scheduled Device Lockdown using SET_DEVICE_LOCKDOWN_STATE API

Android

This article explains how to set up automatic, recurring device lockdown on a schedule (for example, 12 PM–1 PM on weekdays) using the Esper Device Command API. The Esper Console does not have a built-in UI for scheduling recurring lockdowns, so you'll need to use the API with a RECURRING schedule type.

Before you begin

You'll need:

Your Esper tenant name
Your enterprise ID (available in the Esper Console)
The group ID or device UUID(s) you want to lock (find these in Devices & Groups)
An API authentication token for your Esper account
A way to run scheduled scripts (such as a cron job on Linux/macOS or Task Scheduler on Windows)

Step 1: Lock devices on a recurring schedule via API

Send a POST request to the Esper command endpoint with "schedule": "RECURRING" and your desired time window.

To lock a device group (recommended):

POST https://<tenant_name>-api.esper.cloud/api/v0/enterprise/<enterprise_id>/command/

{
 "command_type": "GROUP",
 "groups": ["<group_id>"],
 "group_type": "all",
 "command": "SET_DEVICE_LOCKDOWN_STATE",
 "command_args": {
 "state": "LOCKED",
 "message": "Scheduled weekday lockdown 12PM-1PM"
 },
 "schedule": "RECURRING",
 "schedule_args": {
 "name": "weekday-lockdown",
 "window_start_time": "12:00:00",
 "window_end_time": "13:00:00",
 "time_type": "device",
 "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
 }
}

To lock individual devices instead:

{
 "command_type": "DEVICE",
 "devices": ["<device-uuid-1>", "<device-uuid-2>"],
 "device_type": "all",
 "command": "SET_DEVICE_LOCKDOWN_STATE",
 "command_args": {
 "state": "LOCKED",
 "message": "Scheduled weekday lockdown 12PM-1PM"
 },
 "schedule": "RECURRING",
 "schedule_args": {
 "name": "weekday-lockdown",
 "window_start_time": "12:00:00",
 "window_end_time": "13:00:00",
 "time_type": "device",
 "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
 }
}

Replace the following values:

<tenant_name> — your Esper tenant name
<enterprise_id> — your enterprise UUID (visible in the Esper Console)
<group_id> — the UUID of your target device group (find it in Devices & Groups → [Your Group] → Group Details)
<device-uuid-1>, <device-uuid-2> — individual device UUIDs if targeting specific devices

How the schedule works:

"time_type": "device" means each device uses its own local time zone for the lockdown window
"days" specifies which days the lockdown repeats (Monday through Friday in this example)
"window_start_time" and "window_end_time" define when lockdown begins and ends

Step 2: Unlock devices after the lockdown window

Device lockdown persists until you explicitly unlock it. There is no automatic unlock, so you must send a separate API call to unlock your devices. Send another POST request at the end of your lockdown window (for example, 1:00 PM):

{
 "command_type": "GROUP",
 "groups": ["<group_id>"],
 "group_type": "all",
 "command": "SET_DEVICE_LOCKDOWN_STATE",
 "command_args": {
 "state": "UNLOCKED"
 },
 "schedule": "RECURRING",
 "schedule_args": {
 "name": "weekday-unlock",
 "window_start_time": "13:00:00",
 "window_end_time": "13:05:00",
 "time_type": "device",
 "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
 }
}

Step 3: Automate the lock and unlock calls

To avoid making manual API calls every day, wrap both the lock and unlock requests in a script and run it automatically using a scheduler:

Linux/macOS: Use cron to schedule the script at specific times
Windows: Use Task Scheduler to trigger the script at your desired times

This way, your devices lock and unlock on schedule without any manual intervention.

Step 4: Verify the lockdown is working

After the first scheduled window, confirm that the command executed successfully:

Open the Esper Console and navigate to Devices & Groups → [Your Device or Group] → Activity
Look for the SET_DEVICE_LOCKDOWN_STATE command and verify its status is Success
On your device, check that the screen displays your lockdown message and prevents user interaction during the scheduled window

Troubleshooting

Devices remain accessible during the lockdown window:

Verify that your Esper Device Command agent is online and has an active connection to your device
Offline devices will queue the command but won't execute it until they reconnect
Check that the device's system time zone is correctly configured — Esper uses the Android system time zone for local-time scheduling

The command shows success but has no effect:

Confirm that your group ID is correct and the group is not empty by checking Devices & Groups
Verify that the group contains the devices you intended to lock

Unlock calls are not working:

Ensure you are sending the unlock request with "state": "UNLOCKED" at the correct time
Check the API response for any error messages

Still need help?

If your devices are not locking or unlocking as expected, or if you encounter API errors submit a support ticket. Include the command you sent,