Guides

SmartThings Schema reference

This reference provides information about interaction types, field descriptions, error handling, examples, and other specification requirements.

NOTE

All parameters are required unless otherwise specified.

Schema info

  • “schema”: “st-schema”
  • “version”: “1.0”

Interaction types

The interaction type is located in the payload headers.interactionType. The token context for the request in indicated in authentication.token.

Example

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "discoveryRequest",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token-recevied during oauth from partner"
  }
}

Interaction requests

You must implement the following interaction types:

  • discoveryRequest: Request for devices. Your server will respond with initial list of devices.
  • stateRefreshRequest: Request for the states of the indicated devices. Your server will respond with the states of the indicated devices.
  • commandRequest: Request to issue commands for the indicated device. Your server will issue commands to the device and optionally return the state of the device.

NOTE

Automatic polling occurs approximately every 6 hours.

Interaction responses

The corresponding interaction types when responding to SmartThings request:

  • discoveryResponse: Interaction response for discoveryRequest.
  • stateRefreshResponse: Interaction response for stateRefreshRequest.
  • commandResponse: Interaction response for commandRequest

Additional interaction types

  • callback: (Optional) Interaction type allowing third party to push device state to SmartThings.
  • grantCallbackAccess: (Optional) Your server must implement this request to receive an access token for use with the callback interaction type for authentication.

Callback interaction

Callback interactions allow the third party to push the latest device state information to SmartThings.

Example request

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "callback",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "<SmartThings callback token>"
  },
  "deviceState": [
    {
      "externalDeviceId": "pdevice-1",
      "deviceCookie": {"updatedcookie": "old or new value"},
      "states": [
        {
          "component": "main",
          "capability": "st.switch",
          "attribute": "switch",
          "value": "on"
        },
        {
          "component": "main",
          "capability": "st.switchLevel",
          "attribute": "level",
          "value": 80
        },
        {
          "component": "main",
          "capability": "st.healthCheck",
          "attribute": "healthStatus",
          "value": "online"
        }
      ]
    },
    {
      "externalDeviceId": "pdevice-2",
      "deviceCookie": {"updatedcookie2": "old or new value"},
      "states": [
        {
          "component": "main",
          "capability": "st.switch",
          "attribute": "switch",
          "value": "off"
        },
        {
          "component": "main",
          "capability": "st.switchLevel",
          "attribute": "level",
          "value": 80
        },
        {
          "component": "main",
          "capability": "st.healthCheck",
          "attribute": "healthStatus",
          "value": "offline"
        }
      ]
    }
  ]
}
  • authentication
    • tokenType: Token type.
    • token: Token received from SmartThings.
  • deviceState: (Optional) Array of device states.
    • externalDeviceID: Third-party device ID.
    • deviceCookie: (Optional) Pass-through cookie for setting custom key/value pairs. Should not contain personally identifiable information.

Discovery interaction

Handle the request by retrieving an initial list of devices.

Example request

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "discoveryRequest",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token-recevied during oauth from partner"
  }
}
  • headers
    • schema: Schema type.
    • version: Schema version.
    • interactionType: Interaction type of payload.
    • requestId: Matching request ID from request.
  • authentication
    • tokenType: Token type.
    • token: Token issued by third-party cloud; the context for the request.

Example response

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "discoveryResponse",
    "requestId": "abc-123-456"
  },
  "devices": [
    {
      "externalDeviceId": "pdevice-1",
      "friendlyName": "Kitchen Bulb",
      "manufacturerInfo": {
        "manufacturerName": "LIFX",
        "modelName": "A19 Color Bulb",
        "hwVersion": "v1 US bulb",
        "swVersion": "23.123.231"
      },
      "deviceContext": {
        "roomName": "Kitchen",
        "groups": ["Kitchen Lights", "House Bulbs"],
        "deviceCategory": "light"
      },
      "deviceHandlerType": "c2c-rgbw-color-bulb"
    },
    {
      "externalDeviceId": "pdevice-2",
      "friendlyName": "Toaster",
      "manufacturerInfo": {
        "manufacturerName": "LIFX",
        "modelName": "Outlet",
        "hwVersion": "v1 US outlet",
        "swVersion": "3.03.11"
      },
      "deviceContext": {
        "roomName": "Living Room",
        "groups": ["Hall Lights"],
        "deviceCategory": "light"
      },
      "deviceHandlerType": "<deviceHandlerName-or-deviceProfileId>"
    }
  ]
}
  • headers: See above.
  • devices: Array of devices for user account.
    • externalDeviceId: Device ID at third-party cloud.
    • friendlyName: (Optional) Label of the device shown to the user.
    • manufacturerInfo: Manufacturer info for the device.
      • manufacturerName: Name of the manufacturer, preferably partner name.
      • modelName: Unique model number that identifies the device model.
      • hwVersion: (Optional) Hardware version.
      • swVersion: (Optional) Software/firmware version.
    • deviceContext: Device context info.
      • roomName: Location name associated with the device.
      • groups: Groups that include the device.
      • deviceCategory: Category associated with the device.
    • deviceHandlerType: Device handler type name.

State Refresh interaction

Handle the request by retrieving the device states for the indicated list of devices.

Example request

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "stateRefreshRequest",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token-recevied during oauth from partner"
  },
  "devices": [
    {
      "externalDeviceId": "partner-device-id-1",
    },
    {
      "externalDeviceId": "partner-device-id-2",
      "deviceCookie": {
        "key1": "value1",
        "key2": "value2"
      }
    }
  ]
}
  • headers: See above.
  • authentication: See above.
  • deviceState: Array of device states. See above.

Example response

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "stateRefreshResponse",
    "requestId": "abc-123-456"
  },
  "deviceState": [
    {
      "externalDeviceId": "pdevice-1",
      "deviceCookie": {"updatedcookie": "old or new value"},
      "states": [
        {
          "component": "main",
          "capability": "st.switch",
          "attribute": "switch",
          "value": "on"
        },
        {
          "component": "main",
          "capability": "st.switchLevel",
          "attribute": "level",
          "value": 80
        },
        {
          "component": "main",
          "capability": "st.healthCheck",
          "attribute": "healthStatus",
          "value": "online"
        }
      ]
    },
    {
      "externalDeviceId": "pdevice-2",
      "deviceCookie": {"updatedcookie2": "old or new value"},
      "states": [
        {
          "component": "main",
          "capability": "st.switch",
          "attribute": "switch",
          "value": "off"
        },
        {
          "component": "main",
          "capability": "st.switchLevel",
          "attribute": "level",
          "value": 80
        },
        {
          "component": "main",
          "capability": "st.healthCheck",
          "attribute": "healthStatus",
          "value": "offline"
        }
      ]
    }
  ]
}
  • headers: See above.
  • deviceState: Array of device states.
    • externalDeviceID: Third-party device ID.
    • deviceCookie: (Optional) Pass-through cookie for setting custom key/value pairs. Should not contain personally identifiable information.
    • states
      • component: Component of device. In most cases, the value will be “main”.
      • capability: Capability of device.
      • attribute: Attribute of device.
      • value: The resource value.

Command interaction

Handle the request by triggering the commands for the list of devices.

Example request

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "commandRequest",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token-received during oauth from partner"
  },
  "devices": [
    {
      "externalDeviceId": "partner-device-id",
      "deviceCookie": {
        "lastcookie": "cookie value"
      },
      "commands": [
        {
          "component": "main",
          "capability": "st.switchLevel",
          "command": "setLevel",
          "arguments": [80]
        },
        {
          "component": "main",
          "capability": "st.switch",
          "command": "on",
          "arguments": []
        }
      ]
    }
  ]
}
  • headers: See above.
  • authentication: See above.
  • devices
    • externalDeviceId: Device ID on third-party cloud.
    • commands: Array of commands.
      • component: Component of device. In most cases, the value will be “main”.
      • capability: Capability of device.
      • command: Command name.
      • arguments: Array containing command arguments. If not applicable to the capability/attribute, will be empty.

Example response

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "commandResponse",
    "requestId": "abc-123-456"
  },
  "deviceState": [
    {
      "externalDeviceId": "partner-device-id",
      "deviceCookie": {
        "updatedcookie": "old or new value"
      },
      "states": [
        {
          "component": "main",
          "capability": "st.switch",
          "attribute": "switch",
          "value": "off"
        },
        {
          "component": "main",
          "capability": "st.switchLevel",
          "attribute": "level",
          "value": 80
        },
        {
          "component": "main",
          "capability": "st.healthCheck",
          "attribute": "healthStatus",
          "value": "offline"
        }
      ]
    }
  ]
}
  • headers: See above.
  • deviceState: (Optional) Array of device states. See above.

Error responses

Errors can be appended using global errors or device errors in your interaction type response.

Example global error

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "stateRefreshResponse",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token-issued-by-3rd-party"
  },
  "globalError": {
    "errorEnum": "TOKEN-EXPIRED",
    "detail": "The token has expired"
  },
  "deviceState": [
    {
      "externalDeviceId": "pdevice-1",
      "deviceError": [
        {
          "errorEnum": "<enum>",
          "detail": "messageDetail"
        }
      ]
    }
  ]
}

Append a globalError field to the root of your JSON response for an interaction type.

  • errorEnum: Global error enum type (see below).
  • details: Message for the error.

Global error enum types

  • TOKEN-EXPIRED: Token has expired.
  • INTEGRATION-DELETED: User has removed the integration, so both accessToken and refreshToken are invalid. Used to indicate user needs to re-authorize.

Example device error

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "stateRefreshResponse",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token-issued-by-3rd-party"
  },
  "deviceState": [
    {
      "externalDeviceId": "pdevice-1",
      "deviceError": [
        {
          "errorEnum": "DEVICE-OFFLINE",
          "detail": "This is offline for unknown reasons"
        }
      ]
    }
  ]
}

Append a deviceError field to the stateRefreshResponse or commandResponse interaction response.

  • errorEnum: Device error enum type (see below).
  • details: Message for the error.

Device error enum types

  • DEVICE-OFFLINE: Device is offline and cannot accept commands.
  • DEVICE-DELETED: Device is deleted and cannot accept commands.
  • RESOURCE-CONSTRAINT-VIOLATION: Value is out of range or not acceptable.
  • DEVICE-UNAVAILABLE: Device is unavailable because of a f/w update, maintenance, etc. For use when temporarily unavailable for known reasons. Otherwise should use DEVICE-OFFLINE.
  • CAPABILITY-NOT-SUPPORTED: Command requested is not supported by the device.