--- title: "Create a Subscription for an Installed App" method: POST path: "/installedapps/{installedAppId}/subscriptions" tags: ["Subscriptions"] --- # Create a Subscription for an Installed App `POST /installedapps/{installedAppId}/subscriptions` ## Request - Base URL: `https://api.smartthings.com/v1` - URL: `https://api.smartthings.com/v1/installedapps/{installedAppId}/subscriptions` - Auth: one of: - OAuth 2 - Implicit: `https://auth-global.api.smartthings.com` - Scopes: `r:devices:*` - OAuth 2 - Implicit: `https://auth-global.api.smartthings.com` - Scopes: `r:locations:*` - OAuth 2 - Implicit: `https://auth-global.api.smartthings.com` - Scopes: `r:security:locations:*:armstate` - OAuth 2 - Implicit: `https://auth-global.api.smartthings.com` - Scopes: `r:hubs` - OAuth 2 - Implicit: `https://auth-global.api.smartthings.com` - Scopes: `r:scenes:*` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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 Type | Scope required | | ------------------ | ---------------------------------------------------------------------------------------| | DEVICE | `r:devices:$deviceId` | | CAPABILITY | `r:devices:*:*:$capability` or `r:devices:*`, | | MODE | `r:locations:$locationId` or `r:locations:*` | | DEVICE_LIFECYCLE | `r:devices:$deviceId` or `r:devices:*` | | DEVICE_HEALTH | `r:devices:$deviceId` or `r:devices:*` | | SECURITY_ARM_STATE | `r:security:locations:$locationId:armstate` or `r:security:locations:*:armstate` | | HUB_HEALTH | `r:hubs` | | SCENE_LIFECYCLE | `r:scenes:*` | ## Request body - SubscriptionRequest - `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. - `device` DeviceSubscriptionDetail: Details of a subscription of source type DEVICE. The combination of subscribed values must be unique per installed app. - `deviceId` string, ^(?:([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}))$, required: The GUID of the device that is subscribed to. - `componentId` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: The component ID on the device that is subscribed to or * for all. - `capability` string: Name of the capability that is subscribed to or * for all. - `attribute` string: Name of the capabilities attribute or * for all. - `value` object: A particular value for the attribute that will trigger the subscription or * for all. - `stateChangeOnly` boolean: Only execute the subscription if the subscribed event is a state change from previous events. - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. Must be unique per installed app. - `modes` string[]: List of mode ID's that the subscription will execute for. If not provided then all modes will be supported. - `capability` CapabilitySubscriptionDetail: Details of a subscription of source type CAPABILITY. The combination of subscribed values must be unique per installed app. - `locationId` string, ^(?:([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}))$, required: The id of the location that both the app and source device are in. - `capability` string, required: Name of the capability that is subscribed to. - `attribute` string: Name of the capabilities attribute or * for all. - `value` object: A particular value for the attribute that will trigger the subscription or * for all. - `stateChangeOnly` boolean: Only execute the subscription if the subscribed event is a state change from previous events. - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. Must be unique per installed app. - `modes` string[]: List of modes that the subscription will execute for. If not provided then all modes will be supported. - `mode` ModeSubscriptionDetail: Details of a subscription of source type MODE. This will subscribe to all mode changes for the given location. The installed app can then act on the resulting mode change event accordingly. - `locationId` string, ^(?:([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}))$, required: The GUID for the location to subscribe to mode changes. - `deviceLifecycle` DeviceLifecycleDetail: Details of a subscription of source type DEVICE_LIFECYCLE. Only one of deviceIds or locationId should be supplied. - `deviceIds` string[]: An array of GUIDs of devices being subscribed to. A max of 20 GUIDs are allowed. - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. - `locationId` string, ^(?:([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 location that both the app and source device are in. - `deviceHealth` DeviceHealthDetail: Details of a subscription of source type DEVICE_HEALTH. Only one of deviceIds or locationId should be supplied. - `deviceIds` string[]: An array of GUIDs of devices being subscribed to. A max of 20 GUIDs are allowed. - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. - `locationId` string, ^(?:([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 location that both the app and source device are in. - `securityArmState` SecurityArmStateDetail: Details of a subscription of souce type SECURITY_ARM_STATE - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. - `locationId` string, ^(?:([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}))$, required: The id of the location that both the app and the security system are in. - `hubHealth` HubHealthDetail: Details of a subscription of souce type HUB_HEALTH - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. - `locationId` string, ^(?:([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}))$, required: The id of the location that both the app and hubs are in - `sceneLifecycle` SceneLifecycleDetail: Details of a subscription of source type SCENE_LIFECYCLE. - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. - `locationId` string, ^(?:([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}))$, required: The id of the location that both the app and scenes are in. ## Response `200` The subscription - Subscription - `id` string, ^(?:([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. - `installedAppId` string, ^(?:([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. - `device` DeviceSubscriptionDetail: Details of a subscription of source type DEVICE. The combination of subscribed values must be unique per installed app. - `deviceId` string, ^(?:([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}))$, required: The GUID of the device that is subscribed to. - `componentId` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: The component ID on the device that is subscribed to or * for all. - `capability` string: Name of the capability that is subscribed to or * for all. - `attribute` string: Name of the capabilities attribute or * for all. - `value` object: A particular value for the attribute that will trigger the subscription or * for all. - `stateChangeOnly` boolean: Only execute the subscription if the subscribed event is a state change from previous events. - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. Must be unique per installed app. - `modes` string[]: List of mode ID's that the subscription will execute for. If not provided then all modes will be supported. - `capability` CapabilitySubscriptionDetail: Details of a subscription of source type CAPABILITY. The combination of subscribed values must be unique per installed app. - `locationId` string, ^(?:([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}))$, required: The id of the location that both the app and source device are in. - `capability` string, required: Name of the capability that is subscribed to. - `attribute` string: Name of the capabilities attribute or * for all. - `value` object: A particular value for the attribute that will trigger the subscription or * for all. - `stateChangeOnly` boolean: Only execute the subscription if the subscribed event is a state change from previous events. - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. Must be unique per installed app. - `modes` string[]: List of modes that the subscription will execute for. If not provided then all modes will be supported. - `mode` ModeSubscriptionDetail: Details of a subscription of source type MODE. This will subscribe to all mode changes for the given location. The installed app can then act on the resulting mode change event accordingly. - `locationId` string, ^(?:([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}))$, required: The GUID for the location to subscribe to mode changes. - `deviceLifecycle` DeviceLifecycleDetail: Details of a subscription of source type DEVICE_LIFECYCLE. Only one of deviceIds or locationId should be supplied. - `deviceIds` string[]: An array of GUIDs of devices being subscribed to. A max of 20 GUIDs are allowed. - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. - `locationId` string, ^(?:([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 location that both the app and source device are in. - `deviceHealth` DeviceHealthDetail: Details of a subscription of source type DEVICE_HEALTH. Only one of deviceIds or locationId should be supplied. - `deviceIds` string[]: An array of GUIDs of devices being subscribed to. A max of 20 GUIDs are allowed. - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. - `locationId` string, ^(?:([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 location that both the app and source device are in. - `securityArmState` SecurityArmStateDetail: Details of a subscription of souce type SECURITY_ARM_STATE - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. - `locationId` string, ^(?:([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}))$, required: The id of the location that both the app and the security system are in. - `hubHealth` HubHealthDetail: Details of a subscription of souce type HUB_HEALTH - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. - `locationId` string, ^(?:([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}))$, required: The id of the location that both the app and hubs are in - `sceneLifecycle` SceneLifecycleDetail: Details of a subscription of source type SCENE_LIFECYCLE. - `subscriptionName` string, ^[-_!.~'()*0-9a-zA-Z]{1,36}$: A name for the subscription that will be passed to the installed app. - `locationId` string, ^(?:([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}))$, required: The id of the location that both the app and scenes are in. ## Other responses - `400`: Bad request - `401`: Unauthorized - `403`: Forbidden - `409`: Conflict - `422`: Unprocessable Entity - `429`: Too many requests - `default`: Unexpected error ## Changes - **2026-11-07** `2788a4236800`: 2 info - the security scope `r:devices:*` was added to the endpoint's security scheme `Bearer` - the security scope `r:scenes:*` was removed from the endpoint's security scheme `Bearer` - **2026-07-27** `145c21700100`: 2 info - the security scope `r:devices:*` was added to the endpoint's security scheme `Bearer` - the security scope `r:scenes:*` was removed from the endpoint's security scheme `Bearer` - **2026-01-22** `6acc46f51053`: 2 info - the security scope `r:devices:*` was added to the endpoint's security scheme `Bearer` - the security scope `r:scenes:*` was removed from the endpoint's security scheme `Bearer` - **2025-05-16** `b04d2dce35dd`: 2 info - the security scope `r:devices:*` was added to the endpoint's security scheme `Bearer` - the security scope `r:scenes:*` was removed from the endpoint's security scheme `Bearer` - **2025-02-11** `32f2af0e7ed1`: 2 info - the security scope `r:devices:*` was added to the endpoint's security scheme `Bearer` - the security scope `r:scenes:*` was removed from the endpoint's security scheme `Bearer` [Operation history](https://skmtc.dev/smartthings/apis/smartthings-api/changes/installedapps/:installedAppId/subscriptions/post.md) --- [API](https://skmtc.dev/smartthings/apis/smartthings-api.md) - [All operations](https://skmtc.dev/smartthings/apis/smartthings-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smartthings/apis/smartthings-api/revisions/2788a4236800?raw)