SMsmartthings
Devices

Update a Device

Update the properties of a device.

If the OAuth token used for this call is for a SmartApp that created the device you are attempting to update, the call implicitly has permission for this API.

put/devices/{deviceId}

Request

Request body

labelstring

The label for the device.

locationIdstring ^(?:([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 where the Device should be moved to. Not all Devices support Location moves. Moving between some Locations may be rejected depending on the data region used.

roomIdstring ^(?:([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 Room with which to associate the Device is associated. The Room must be valid for the Location of the Device.

Example request

{
  "label": "Living room light",
  "locationId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
  "roomId": "0fd2b1ef-1b33-4a54-9153-65aca91e9660",
  "components": [
    {
      "id": "main",
      "label": "living room light switch 2",
      "icon": "string",
      "categories": [
        "Light"
      ]
    }
  ],
  "indoorMap": {
    "coordinates": [
      1,
      2,
      3
    ],
    "rotation": [
      0,
      0,
      0
    ],
    "visible": true
  }
}

Response

Updated device.

deviceIdstring required

The identifier for the device instance.

namestring

The name that the device integration (Device Handler or SmartApp) defines for the device.

labelstring

The name that a user chooses for the device. This defaults to the same value as name.

manufacturerNamestring required

The device manufacturer name.

presentationIdstring required

A non-unique id that is used to help drive UI information.

deviceManufacturerCodestring

The device manufacturer code.

locationIdstring ^(?:([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 with which the device is associated.

ownerIdstring

The identifier for the owner of the device instance.

roomIdstring ^(?:([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 room with which the device is associated. If the device is not associated with any room, this field will be null.

deviceTypeIdstring ^(?:([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}))$

Deprecated please look under "dth".

deviceTypeNamestring

Deprecated please look under "dth".

deviceNetworkTypestring

Deprecated please look under "dth".

productIdstring ^[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 device's product ID. If the device is not associated with any product, this field will be null.

brandIdstring ^[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 device's brand ID. If the device is not associated with any brand, this field will be null.

createTimestring

The time when the device was created at.

parentDeviceIdstring

The id of the Parent device.

childDevicesDevice[] circular
bleBleDeviceDetails
type'BLE' | 'BLE_D2D' | 'DTH' | 'ENDPOINT_APP' | 'GROUP' | 'HUB' | 'IR' | 'IR_OCF' | 'LAN' | 'MATTER' | 'MOBILE' | 'MQTT' | 'OCF' | 'SAFER' | 'STPRO' | 'PENGYOU' | 'SHP' | 'VIDEO' | 'VIPER' | 'VIRTUAL' | 'WATCH' | 'ZIGBEE' | 'ZWAVE' | 'EDGE_CHILD' required

The type of device integration (may be null). If the type is DTH, the device implementation is a groovy Device Handler and the details are in the "dth" field. If the type is ENDPOINT_APP, the device implementation is a SmartApp and the details are in the "app" field. If the type is IR, the details are in the "ir" field. If the type is IR_OCF, the details are in the "irOcf" field. If the type is OCF, the details are in the "ocf" field. If the type is VIPER, the details are in the "viper" field.

restrictionTierinteger required

Restriction tier of the device, if any.

allowedstring[]

List of client-facing action identifiers that are currently permitted for the user. If the value of this property is not null, then any action not included in the list value of the property is currently prohibited for the user. If the value of this property is null (or absent), then no permission-related information is being provided.

<ul> <li> w:devices - the user can change device details <li> w:devices:locationId - the user can move the device from a location <li> w:devices:roomId - the user can move or remove the device from a room <li> x:devices - the user can execute commands on the device <li> d:devices - the user can uninstall the device </ul>
executionContext'LOCAL' | 'CLOUD'

Where device executes -- locally, in the cloud, or perhaps other in the future. Defaults to CLOUD.

  • 'LOCAL' - executes on the hub
  • 'CLOUD' - executes in the cloud

Example response

{
  "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
  "name": "color.light.100x",
  "label": "color.light.100x",
  "manufacturerName": "SmartThings",
  "presentationId": "VD-STV_2018_K",
  "deviceManufacturerCode": "010F-0B01-2002",
  "locationId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
  "ownerId": "1c75f712-2c3e-4e51-970c-a42ae7aedbdc",
  "roomId": "0fd2b1ef-1b33-4a54-9153-65aca91e9660",
  "deviceTypeId": "Deprecated please look under \"dth\".",
  "deviceTypeName": "Deprecated please look under \"dth\".",
  "deviceNetworkType": "Deprecated please look under \"dth\".",
  "productId": "48bea670-2bb3-494f-a402-dbc5a7cf1e06",
  "brandId": "cb1332ca-8dd6-422f-b2ab-e757d9abf694",
  "components": [
    {
      "id": "main",
      "capabilities": [
        {
          "id": "switch",
          "version": 1,
          "config": {
            "values": [
              {
                "key": "thermostatMode.value"
              }
            ]
          },
          "status": {
            "switch": {
              "value": "on"
            }
          }
        }
      ],
      "categories": [
        {
          "name": "Light"
        }
      ]
    }
  ],
  "profile": {
    "id": "a7b3c264-2d22-416e-bca1-ca4b59a60aee"
  },
  "app": {
    "installedAppId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
    "externalId": "Th13390",
    "profile": {
      "id": "a7b3c264-2d22-416e-bca1-ca4b59a60aee"
    }
  },
  "bleD2D": {
    "encryptionKey": "96012869B606355A1F843B1E19DC31B1",
    "cipher": "BMO_256-CBS-PKMS1Padding",
    "gattCipher": "BMO_256-CBS-PKMS1Padding",
    "advertisingId": "9C0D4219",
    "identifier": "88-57-1d-0e-53-ab",
    "configurationUrl": "https://apisa.samsungiots.com/v1/miniature/profile/e524ceba-93b9-499d-a90a-24214f7f01cb",
    "bleDeviceType": "BLE, TAG, DOORLOCK, HEALTH"
  },
  "dth": {
    "deviceNetworkType": "ZIGBEE",
    "deviceTypeId": "7b8514e6-230d-41cc-b3c2-512bca15abf0",
    "deviceTypeName": "x.com.samsung.da.fridge",
    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
    "installedGroovyAppId": "8f5ra619-4c05-4a90-a245-cc129b0a8098",
    "fingerprintId": "smartthings.motion-v4"
  },
  "lan": {
    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
    "fingerprintId": "smartthings.motion-v4"
  },
  "zigbee": {
    "eui": "24FD5B000105DB96",
    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
    "fingerprintId": "smartthings.motion-v4"
  },
  "zwave": {
    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
    "manufacturerId": 134,
    "productType": 17488,
    "productId": 12336,
    "fingerprintId": "smartthings.motion-v4"
  },
  "matter": {
    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
    "version": {
      "hardware": 771,
      "software": 50529027
    },
    "endpoints": [
      {
        "endpointId": 771,
        "deviceTypes": [
          {
            "deviceTypeId": 197379
          }
        ]
      }
    ],
    "syncDrivers": true,
    "fingerprintId": "smartthings.motion-v4"
  },
  "hub": {
    "hubEui": "D053A8B4F6D80001",
    "hubDrivers": [
      {
        "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
        "channelId": "9314a926-528c-403f-ae56-4b0d059381dd"
      }
    ],
    "hubData": {
      "zwaveStaticDsk": "21720-31296-41384-03009-58023-25366-38831-43982",
      "hardwareType": "V3_HUB",
      "hardwareId": "00A2",
      "zigbeeFirmware": "5.4.0",
      "failoverAvailability": "Available",
      "primarySupportAvailability": "Available",
      "secondarySupportAvailability": "Available",
      "zigbeeAvailability": "Available",
      "zwaveAvailability": "Available",
      "threadAvailability": "Available",
      "lanAvailability": "Available",
      "matterAvailability": "Available",
      "localVirtualDeviceAvailability": "Available",
      "childDeviceAvailability": "Available",
      "edgeDriversAvailability": "Available",
      "hubReplaceAvailability": "Available",
      "hubLocalApiAvailability": "Available",
      "edgeDriverSupportedEndpointApps": {
        "apps": [
          {
            "appName": "Sonos",
            "version": "v1"
          }
        ]
      },
      "repeaterReachability": "Unreachable",
      "matterRendezvousHedgeSupported": true,
      "matterCommissionerSupport": {
        "supportedModes": [
          "ON_NETWORK",
          "BLE"
        ]
      },
      "matterSoftwareComponentVersion": "1.2-0",
      "matterDeviceDiagnosticsAvailability": "Available",
      "zigbeeDeviceDiagnosticsAvailability": "Available",
      "hedgeTlsCertificate": "-----BEGIN CERTIFICATE----- 1A2b3C4d... -----END CERTIFICATE-----",
      "hub2hubSupportMatrix": {
        "capabilities": [
          {
            "name": "HEDGE",
            "version": 1
          }
        ]
      }
    },
    "driverId": "a5e05a41-0b0a-4d07-a825-b85e9543fc1b"
  },
  "edgeChild": {
    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
    "fingerprintId": "smartthings.motion-v4"
  },
  "ir": {
    "profileId": "0c0b875r-0213-6479-a0bf-da7aeec3dc0a",
    "ocfDeviceType": "oic.d.tv",
    "irCode": "006C",
    "functionCodes": {
      "statelessPowerToggleButton.powerToggle": "power",
      "statelessAudioMuteButton.muteToggle": "mute",
      "statelessAudioVolumeButton.volumeUp": "volume_up",
      "statelessAudioVolumeButton.volumeDown": "volume_down",
      "statelessChannelButton.channelUp": "channel_up",
      "statelessChannelButton.channelDown": "channel_down",
      "statelessCustomButton.green": "green",
      "statelessCustomButton.right": "right",
      "statelessCustomButton.3": 3,
      "statelessCustomButton.exit": "exit",
      "statelessCustomButton.playback": "playback"
    }
  },
  "irOcf": {
    "profileId": "0c0b875r-0213-6479-a0bf-da7aeec3dc0a",
    "ocfDeviceType": "oic.d.tv",
    "irCode": "006C",
    "functionCodes": {
      "statelessPowerToggleButton.powerToggle": "power",
      "statelessAudioMuteButton.muteToggle": "mute",
      "statelessAudioVolumeButton.volumeUp": "volume_up",
      "statelessAudioVolumeButton.volumeDown": "volume_down",
      "statelessChannelButton.channelUp": "channel_up",
      "statelessChannelButton.channelDown": "channel_down",
      "statelessCustomButton.green": "green",
      "statelessCustomButton.right": "right",
      "statelessCustomButton.3": 3,
      "statelessCustomButton.exit": "exit",
      "statelessCustomButton.playback": "playback"
    }
  },
  "viper": {
    "uniqueIdentifier": "1a-74",
    "manufacturerName": "TP-Link",
    "modelName": "HS101",
    "swVersion": "23.123.231",
    "hwVersion": "v1 US bulb",
    "endpointAppId": "viper_bb238c20-675a-11ed-970f-571777eb58c5"
  },
  "group": {
    "groupName": "My Group",
    "devices": [
      {
        "deviceId": "747d79d3-4685-4852-89b6-e2fc681a590f",
        "components": [
          {
            "id": "main"
          }
        ]
      }
    ]
  },
  "virtual": {
    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd"
  },
  "indoorMap": {
    "coordinates": [
      "1.0",
      "2.0",
      "3.0"
    ],
    "rotation": [
      "0",
      "0",
      "0"
    ],
    "visible": true,
    "data": [
      {
        "extraData1": "some data"
      }
    ]
  },
  "relationships": [
    {
      "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3"
    }
  ]
}

Changes

No recorded changes to this operation across all 8 revisions of this API.