SmartThings Schema

The SmartThings Schema is a specification for use in a cloud-connected device integration. It does not require using the SmartThings API.

When using the Schema for a cloud-connected device integration, you must:

  1. Create an OAuth2 client from your cloud.
  2. Register a Connector in the Developer Workspace that can fulfill requests sent from SmartThings.
  3. Implement the Schema in the HTTPS response.
  4. Test your integration.

The Schema defines the format of the JSON payloads sent from your server.

Basic concept

The SmartThings Schema recognizes three interaction types that define how your server responds to SmartThings.

  • Discovery: Return a list of devices.
  • State Refresh: Return the state of the devices.
  • Command: Issue commands to the device.

SmartThings specifies an interaction type when sending a request to your server, which replies with the appropriate information in a JSON payload.

Cloud Connector

You will set up a Connector to handle the interaction types. This Connector can be a WebHook endpoint or AWS Lambda function.

See Integrate a cloud-connected device for details on setting up the Connector.


You must generate an OAuth2 application from your cloud. You supply the OAuth2 credentials and details for your application when registering your Connector in Developer Workspace.

When creating your OAuth2 application, you will need to supply the following SmartThings redirect URIs:

  • (United States)
  • (European Union)
  • (Asia-Pacific)