SMsmartthings
Subscriptions

Create a Subscription for an Installed App

Changed on

Create a subscription to a type of event from the specified source. Both the source and the installed app must be in the location specified and the installed app must have read access to the event being subscribed to. An installed app is only permitted to created 20 subscriptions.

Authorization scopes

For installed app principal:

  • installed app id matches the incoming request installed app id location must match the installed app location
Subscription TypeScope required
DEVICEr:devices:$deviceId
CAPABILITYr:devices:*:*:$capability or r:devices:*,
MODEr:locations:$locationId or r:locations:*
DEVICE_LIFECYCLEr:devices:$deviceId or r:devices:*
DEVICE_HEALTHr:devices:$deviceId or r:devices:*
SECURITY_ARM_STATEr:security:locations:$locationId:armstate or r:security:locations:*:armstate
HUB_HEALTHr:hubs
SCENE_LIFECYCLEr:scenes:*
post/installedapps/{installedAppId}/subscriptions

Request

  • Base URL
    https://api.smartthings.com/v1
  • Auth
    • OAuth 2
      Implicithttps://auth-global.api.smartthings.com
      Scopesr:devices:*
    • or OAuth 2
      Implicithttps://auth-global.api.smartthings.com
      Scopesr:locations:*
    • or OAuth 2
      Implicithttps://auth-global.api.smartthings.com
      Scopesr:security:locations:*:armstate
    • or OAuth 2
      Implicithttps://auth-global.api.smartthings.com
      Scopesr:hubs
    • or OAuth 2
      Implicithttps://auth-global.api.smartthings.com
      Scopesr:scenes:*
  • TypeScript
    A function with typed inputs. Its response is checked against the schema.

Request body

sourceType'DEVICE' | 'CAPABILITY' | 'MODE' | 'DEVICE_LIFECYCLE' | 'DEVICE_HEALTH' | 'SECURITY_ARM_STATE' | 'HUB_HEALTH' | 'SCENE_LIFECYCLE' required

The type of the event that is being subscribed to.

Example request

{
  "sourceType": "DEVICE",
  "device": {
    "deviceId": "736e3903-001c-4d40-b408-ff40d162a06b",
    "componentId": "freezer",
    "capability": "temperatureMeasurement",
    "attribute": "temperature",
    "stateChangeOnly": true,
    "modes": [
      "e34b57fb-e73a-4228-8819-e99502d17890",
      "cfa3a42e-5f52-452e-9515-c32bcbea48ce"
    ]
  }
}

Response

The subscription

idstring ^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$

The id of the subscription.

installedAppIdstring ^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$

The id of the subscribing app.

sourceType'DEVICE' | 'CAPABILITY' | 'MODE' | 'DEVICE_LIFECYCLE' | 'DEVICE_HEALTH' | 'SECURITY_ARM_STATE' | 'HUB_HEALTH' | 'SCENE_LIFECYCLE'

The type of the event that is being subscribed to.

Example response

{
  "id": "5e1b134b-bd85-4125-9c25-4a8291e754aa",
  "installedAppId": "fb05c874-cf1d-406a-930c-69a081e0eaee",
  "sourceType": "DEVICE",
  "device": {
    "componentId": "main",
    "deviceId": "e457978e-5e37-43e6-979d-18112e12c961,",
    "capability": "contactSensor,",
    "attribute": "contact,",
    "stateChangeOnly": "true,",
    "subscriptionName": "contact_subscription',",
    "value": "*"
  }
}

Changes

  • 2788a4236800Revision changes
    • info

      the security scope r:devices:* was added to the endpoint's security scheme Bearer

    • info

      the security scope r:scenes:* was removed from the endpoint's security scheme Bearer

  • 145c21700100Revision changes
    • info

      the security scope r:devices:* was added to the endpoint's security scheme Bearer

    • info

      the security scope r:scenes:* was removed from the endpoint's security scheme Bearer