Scheduling

SmartApps may schedule future executions using the Scheduling API.

Two types of scheduled executions are supported:

  • Once schedules are created to be executed exactly once at the specified day and time.
  • Cron schedules are created according to a Cron expression. These expressions may define recurring schedules (e.g., execute every fifteen minutes).

Creating scheduled executions

Creating schedules requires that the SmartApps have permission to create schedules.

This requires that the app is created with the w:schedules scope, as well as request the w:schedules during the INITIALIZE phase of the CONFIGURE lifecycle.

An example response to the INITIALIZE phase to request schedule write permission:

{
  "name": "my app name",
  "description": "my app description",
  "id": "my-app",
  "permissions":["w:schedules"],
  "firstPageId": "1"
}

Once schedules

Once schedules are defined in the number of milliseconds from 1 January 1970 UTC (Unix Time).

The request body for Once schedules look like this:

{
  "name": "",
  "once": 1587409157
}

Here is an example request to create a Once schedule:

curl -X POST -H "Authorization: Bearer " \
    ST_API_URL/installedapps//schedules
    -d "{'name': 'schedule-name', 'once': 1587409157}"
const request = require('request');
request.post({
  url: "https://api.smartthings.com/installedapps//schedules",
  json: true,
  headers: {
    'Authorization': 'Bearer '
  },
  body: {
    name: 'schedule-name',
    once: 1587409157
  }
}, function(err, req, resp) {
  console.log(`received response ${JSON.stringify(resp)}`);
}});

Cron schedules

Cron schedules use the Quartz Scheduler format, with an important difference: The seconds field is not supported, and is omitted from the cron expression.

All Cron schedules will be assigned a random seconds field by the SmartThings platform.

The request body for Cron schedules looks like this:

{
  "name": "",
  "'cron'": {
    "expression": "0/5 * * * ? *",
    "timezone": "CST"
  }
}

An example request to create a Cron schedule:

curl -X POST -H "Authorization: Bearer " \
    ST_API_URL/installedapps//schedules
    -d "{'name': '', 'cron': {'expression': '0/5 * * * ? *', 'timezone': 'GMT'}}"
const request = require('request');
request.post({
  url: "/installedapps//schedules",
  json: true,
  headers: {
    'Authorization': 'Bearer '
  },
  body: {
    name: '',
    cron: {
      expression: '0/5 * * * ? *',
      timezone: 'GMT'
    }
  }
}, function(err, req, resp) {
  console.log(`received response ${JSON.stringify(resp)}`);
}});

Cron expression examples

Expression Description
"0/5 * * * ? *" Fire every five minutes, every day.
"30 10 * * ? *" Fire every day at 10:30 a.m.
"0/10 9 * * ?" Fire every ten minutes starting at 9 a.m and ending at 9:50 a.m., every day.

Timezones

When creating schedules, consider in what time zone the schedule should be executed in. Usually, this will be the time zone of the installed app. You can get the time zone for the Location that the installed app belongs to by using the Location API__LINK TO API REF DOCS WHEN AVAILABLE__.

Scheduled execution events

When a scheduled execution is triggered by SmartThings, your app is called with an EVENT lifecycle phase payload. It will contain information about the schedule that triggered the execution:

{
  "lifecycle": "EVENT",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "eventData": {
    "authToken": "f01894ce-013a-434a-b51e-f82126fd72e4",
    "installedApp": {
      "installedAppId": "d692699d-e7a6-400d-a0b7-d5be96e7a564",
      "locationId": "e675a3d9-2499-406c-86dc-8a492a886494",
      "config": {
        "contactSensor": [
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "e457978e-5e37-43e6-979d-18112e12c961",
              "componentId": "main"
            }
          }
        ],
        "lightSwitch":[
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
              "componentId": "main"
            }
          }
        ],
        "minutes":[
          {
            "valueType": "STRING",
            "stringConfig": {
              "value": "5"
            }
          }
        ],
        "permissions": [
          "r:devices:e457978e-5e37-43e6-979d-18112e12c961",
          "r:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
          "x:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76"
        ]
      }
    },
    "events": [
      {
        "eventType": "TIMER_EVENT",
        "timerEvent": {
          "eventId": "string",
          "name": "lights_off_timeout",
          "type": "CRON",
          "time": "2017-09-13T04:18:12.469Z",
          "expression": "string"
        }
      }
    ]
  },
  "settings": {
    "property1": "string",
    "property2": "string"
  }
}

Getting schedules

Getting schedules requires that the SmartApps have permission to read schedules.

This requires that the app is created with the r:schedules scope, as well as request the r:schedules during the INITIALIZE phase of the CONFIGURE lifecycle.

A sample response to the INITIALIZE phase to request schedule read and write permission:

{
  "name": "my app name",
  "description": "my app description",
  "id": "my-app",
  "permissions":["w:schedules","r:schedules"],
  "firstPageId": "1"
}

Get a schedule

A specific schedule for an installed app can be retrieved by issuing a GET request to All schedules for an installed app can be retrieved by issuing a GET request to/installedapps/{installedAppId}/schedules/{scheduleName}`:

curl -X GET https://api.smartthings.com/installedapps//schedules/ \
     -H "Authorization: Bearer {TOKEN}"
const request = require('request');
request.get({
  url: "https://api.smartthings.com/installedapps//schedules/",
  json: true,
  headers: {
    'Authorization': 'Bearer '
  }
}, function(err, req, resp) {
  console.log(`received response ${JSON.stringify(resp)}`);
}});

A schedule will be returned:

{
  "scheduledExecutions": [
    1505752823000
  ],
  "name": "weather-check-schedule",
  "cron": {
    "expression": "0/10 * * * ? *",
    "timezone": "America/Chicago"
  },
  "installedAppId": "937e11d5-317d-445f-bec7-3055fdb827a3",
  "locationId": "8418eebd-8d5f-48dd-h028-03474bd1aecb"
}

Get all schedules

All schedules for an installed app can be retrieved by issuing a GET request to /installedapps/{installedAppId}/schedules:

curl -X GET https://api.smartthings.com/installedapps//schedules \
     -H "Authorization: Bearer "
const request = require('request');
request.get({
  url: "https://api.smartthings.com/installedapps//schedules",
  json: true,
  headers: {
    'Authorization': 'Bearer '
  }
}, function(err, req, resp) {
  console.log(`received response ${JSON.stringify(resp)}`);
}});

A paged result of schedules will be returned:

{
  "items": [
    {
      "scheduledExecutions": [
        1505752823000
      ],
      "name": "weather-check-schedule",
      "cron": {
        "expression": "0/10 * * * ? *",
        "timezone": "America/Chicago"
      },
      "installedAppId": "937e11d5-317d-445f-bec7-3055fdb827a3",
      "locationId": "844rgebd-8d5f-48dd-a028-05474bd1aecb"
    }
  ],
  "_links": {
    "next": null,
    "previous": null
  }
}

Deleting schedules

Schedules removed on uninstall

All schedules and subscriptions for an installed app are automatically deleted when a user uninstalls an app.

Deleting schedules requires that the SmartApps have permission to write schedules.

This requires that the app is created with the w:schedules scope, as well as request the w:schedules during the INITIALIZE phase of the CONFIGURE lifecycle.

A sample response to the INITIALIZE phase to request schedule read and write permission:

{
  "name": "my app name",
  "description": "my app description",
  "id": "my-app",
  "permissions":["w:schedules","r:schedules"],
  "firstPageId": "1"
}

Delete a schedule

Individual schedules can be deleted for an installed app by issuing a DELETE request to /installedapps/{installedAppId}/schedules/{scheduleName}:

curl -X DELETE https://api.smartthings.com/installedapps//schedules/ \
     -H "Authorization: Bearer {TOKEN}"
const request = require('request');
request.delete({
  url: "https://api.smartthings.com/installedapps//schedules/",
  json: true,
  headers: {
    'Authorization': 'Bearer '
  }
}, function(err, req, resp) {
  console.log(`received response ${JSON.stringify(resp)}`);
}});

Delete all schedules

All schedules for an installed app can be deleted by issuing a DELETE request to /installedapps/{installedAppId}/schedules:

curl -X DELETE https://api.smartthings.com/installedapps//schedules \
     -H "Authorization: Bearer {TOKEN}"
const request = require('request');
request.delete({
  url: "https://api.smartthings.com/installedapps//schedules",
  json: true,
  headers: {
    'Authorization': 'Bearer '
  }
}, function(err, req, resp) {
  console.log(`received response ${JSON.stringify(resp)}`);
}});

Scheduling limits

Each installed app is limited to having ten pending scheduled executions at any time. Requests to create any additional pending scheduled executions will result in a 422 Unprocessable Entity response.