User service

Updated at:

This document describes a set of user-related service APIs. Client applications can use these APIs to retrieve a list of devices that are attached to a user. You can also use these APIs to detach devices and push channels.

Note The user service has been upgraded with new features, such as home, space, and audience group control. If you do not need these features, see User service (legacy).

User-device attachment relationships

Device sharing

User-message attachment relationships

Virtual users

Get a list of devices attached to a user

Definition

pathVersionDescriptionRequires user identity authentication
/uc/listBindingByAccount1.0.8Gets a list of devices attached to a user.Yes

Request parameters

ParameterTypeRequiredDescription
thingTypeStringNoThe type of the device.
  • VIRTUAL (virtual device)
  • VIRTUAL_SHADOW (virtual shadow device)
  • WEB
  • APP
  • DEVICE (regular device)
nodeTypeStringNoThe node type of the device. Valid values: DEVICE and GATEWAY.
ownedIntegerNoThe attachment type. 0: a shared device. 1: an owned device. null: all devices.
isSubDeviceBooleanNoSpecifies whether the device is a sub-device.
  • true: Get the sub-device list.
  • false: Get the list of non-sub-devices (directly connected devices).
  • null: Get the list of all devices.
A device that belongs to a gateway device is a sub-device. Note: This parameter is valid only for sub-devices attached after January 8, 2020. Data for sub-devices attached before this date cannot be filtered by this field.
pageNoIntegerYesThe page number. The value starts from 1.
pageSizeIntegerYesThe number of entries per page. The value must be greater than or equal to 1 and less than or equal to 100.

Response parameters

ParameterSub-parameterTypeDescription
total-LongThe total number of devices that meet the criteria.
pageNo-IntegerThe page number.
pageSize-IntegerPage size
data-JSONArrayA list of device details.
-identityIdStringThe identity ID of the user.
-iotIdStringThe iotId of the device. This is the unique identifier of the device.
-deviceNameStringThe name of the device.
-productKeyStringThe ProductKey of the product to which the device belongs.
-productNameStringThe name of the product to which the device belongs.
-productImageStringThe icon of the product to which the device belongs. If no product icon is defined, this field has the same value as the categoryImage field.
-productModelStringThe model of the product to which the device belongs.
-categoryImageStringThe icon of the product category to which the device belongs.
-nickNameStringThe nickname of the device. This can be empty.
-netTypeStringThe network connection type of the device. Valid values:
  • NET_LORA (LoRa)
  • NET_CELLULAR (GPRS)
  • NET_WIFI (Wi-Fi)
  • NET_ZIGBEE (ZigBee)
  • NET_ETHERNET (Ethernet)
  • NET_OTHER (Other)
-thingTypeStringThe type of the device.
  • VIRTUAL (virtual device)
  • VIRTUAL_SHADOW (virtual shadow device)
  • WEB
  • APP
  • DEVICE (regular device)
-statusByteThe status of the device. 0: inactive. 1: online. 3: offline. 8: disabled.
-ownedIntegerThe relationship between the device and the user. 0: sharer. 1: owner.
-nodeTypeStringThe node type of the device. Valid values: DEVICE and GATEWAY.
-identityAliasStringThe display name of the user, such as mobile, loginName, or email.
-subDeviceBooleanIndicates whether the device is a sub-device. true: a sub-device. false or null: not a sub-device (a directly connected device).
-gmtModifiedDateThe time when the attachment was modified (attachment time).

Examples

  • Request example
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"en-US",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"
        },
        "params":{
            "isSubDevice":false,
            "pageNo":1,
            "pageSize":10
        }
    }
  • Successful response example
    {
        "id":"4de2c367-xxxx-xxxx-aa15-8c585e595d92",
        "code":200,
        "message":"success",
        "localizedMsg":null,
        "data":{
            "total":2,
            "pageNo":1,
            "pageSize":10,
            "data":[
                {
                    "identityId":"xxx",
                    "iotId":"edwB6TqvxxxxxxNa000100",
                    "deviceName":"Camera1",
                    "productKey":"Product PK",
                    "productName":"Product Name",
                    "productImage":"Product Image",
                    "productModel":"Product Model",
                    "categoryImage":"xxx",
                    "nickName":"Device Nickname",
                    "netType":"NET_WIFI",
                    "thingType":"DEVICE",
                    "status":1,
                    "owned":1,
                    "nodeType":"DEVICE",
                    "identityAlias":"133xxx",
                    "subDevice":false,
                    "gmtModified":"xxx"
                },
                {
                    "identityId":"xxx",
                    "iotId":"xadqskxxxxxx9h000100",
                    "deviceName":"Camera2",
                    "productKey":"Product PK",
                    "productName":"Product Name",
                    "productImage":"Product Image",
                    "productModel":"Product Model",
                    "categoryImage":"xxx",
                    "nickName":"Device Nickname",
                    "netType":"NET_WIFI",
                    "thingType":"DEVICE",
                    "status":1,
                    "owned":1,
                    "nodeType":"DEVICE",
                    "identityAlias":"133xxx",
                    "subDevice":false,
                    "gmtModified":"xxx"
                }
            ]
        }
    }

Get attachment relationships by device

Definition

pathVersionDescriptionRequires user identity authentication
/uc/listBindingByDev1.0.2Gets attachment relationships by device.Yes. The client SDK must enable identity authentication.

Request parameters

ParameterTypeRequiredDescription
iotIdStringYesThe device ID.
pageNoIntYesThe current page number. The value starts from 1.
pageSizeIntYesThe number of entries per page. This is the maximum number of items on a single page.
ownedIntNoThe attachment type of the device. 0: a device shared by others. 1: the device owner. null: all.

Response parameters

ParameterSub-keyTypeDescription
total-IntegerThe total number on the cloud.
pageNo-IntegerThe current page number.
pageSize-IntegerPage size
data-List<>A list of devices attached to the user.
-identityIdStringThe identity ID of the user.
-iotIdStringThe iotId of the device.
-productKeyStringThe ProductKey of the device.
-deviceNameStringDevice Name
-productNameStringThe name of the product.
-productImageStringThe image of the product.
-productModelStringThe model of the product.
-categoryImageStringThe category icon.
-nickNameStringThe nickname of the device set by the user. This is the nickname set using setDeviceNickName.
-netTypeStringThe network connection type of the device.
-thingTypeString The type of the device.
  • VIRTUAL (virtual device)
  • VIRTUAL_SHADOW (virtual shadow device)
  • WEB
  • APP
  • DEVICE (regular device)
- nodeType String The node type of the device: DEVICE, GATEWAY.
- status Byte The status of the device. 0: inactive. 1: online. 3: offline. 8: disabled.
- owned Byte 0: sharer. 1: owner.
- identityAlias String The display name of the user: mobile, loginName, or email.
- gmtModified Date The time when the attachment was modified.
- description String The description.

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c80xxxxxxxxf62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "pageNo":1,
            "pageSize":10,
            "iotId":"fy2Z1oZFxxxxxxxx101edf00"
    
        },
        "version": "1.0"
    }
  • Successful response example
    {
      "code": 200,
      "data": [
        {
          "productModel": "testProduct",
          "iotId": "fy2Z1oZFxxxxxxx00101edf00",
          "netType": "NET_WIFI",
          "identityId": "5082opabf5192xxxxxxxx980ae6f6093",
          "thingType": "DEVICE",
          "nodeType": "DEVICE",
          "productKey": "a1xxxxJNb",
          "deviceName": "b65cb59xxxxxxxx08592cd695fb",
          "productName": "0dxxxx95",
          "status": 3
        }
      ],
      "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
    }
  • Error response example
    {
     "code":2064,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"need authorize to bind"
    }

Sort the device list

Definition

path Version Description Requires user identity authentication
/uc/sortDevices 1.0.2 Sorts the devices. Yes. The client SDK must enable identity authentication.

Request parameters

Parameter Sub-key Type Required Description
sortDeviceDTOList - List<> Yes Data of devices whose sort order has changed.
- iotId String Yes The device ID.
- fromOrder Integer Yes The position of the device before the sort order changed.
- toOrder Integer Yes The position of the device after the sort order changed.

Return parameters

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c80xxxxxxxxf6f62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "sortDeviceDTOList":[
                {"iotId": "Z75bTa4dxxxxxxxxRW001056af10",
                  "fromOrder": 1,
                  "toOrder":  3            
                },
                {"iotId": "faHSHCOxxxxxxxxxZQoN00108dcf00",
                  "fromOrder": 2,
                  "toOrder":  1            
                },
                {"iotId": "Spb4eatt1Lxxxxxxxx00108a4410",
                  "fromOrder": 3,
                  "toOrder":  2            
                }
             ] 
        },
        "version": "1.0"
    }                    
  • Successful response example
    {
        "code": 200,
        "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }
  • Error response example
    {
     "code":2000,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"sortDevice param error!"
    }                    

Generate a QR code for sharing

Definition

path Version Description Requires user identity authentication
/uc/generateShareQrCode 1.0.2 Generates a QR code for sharing devices. Batch sharing is supported. The QR code is valid for 30 minutes. Yes. The client SDK must enable identity authentication.

Request parameters

Parameter Type Required Description
iotIdList List< String > No A list of device iotIds. The list can contain up to 20 iotIds. This parameter cannot be empty.

Response parameters

Parameter Type Description
qrKey String The generated QR code key.

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049cxxxxxxxx6f62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "iotIdList":["xxxx"],
            "sceneIdList":["xxxx"]
        },
        "version": "1.0"
    }
  • Successful response example
    {
        "code": 200,
        "data": {
            "qrKey": "xxxxxx"
        },
        "id": "6ec222eb-87fc-xxxx-xxxx-351df196ceb3"
    }   
  • Error response example
    {
      "code":2081,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"scene not found by sceneId"
    }      

Attach a device or scenario by scanning a QR code

Description

path Version Description Requires user identity authentication
/uc/scanBindByShareQrCode 1.0.8 Attaches a device or scenario by scanning a QR code. After attachment, the user becomes a regular member. Yes. The client SDK must enable identity authentication.

Request parameters

Parameter Type Required Description
qrKey String Yes The key of the scanned QR code.

Response parameters

Parameter Type Description
ScanShareQrCodeV2Resp Object A list of attached device or scenario IDs.
ScanShareQrCodeV2Res structure
Parameter Type Description
iotIdList List A list of attached device or scenario IDs.

Examples

  • Request example
    {
        "request":{
            "iotToken":"109049c80xxxxxxxx6f62e29a3ba",
            "apiVer":"1.0.2"
        },
        "id":150821281****,
        "params":{
            "homeId":"50f5opxxxxxxxxxxxxf28104512",
            "qrKey":"xxxx"
        },
        "version":"1.0"
    } 
  • Successful response example
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":{
            "iotIdList":[
                "CKuX1xxxxxxxxxxxxxxxx00100",
                "vbiM2xxxxxxxxxxxxxxxx00100"
            ]
        },
        "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }
  • Error response example
    {
     "code":2067,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"qrKey not exist"
    }         

Share a device with a specified user

Definition

path Version Description Requires authentication
/uc/shareDevicesAndScenes 1.0.8 Shares devices and scenarios with other users by specifying their mobile number, email address, or identityId. If you use a proprietary account system, the mobile numbers and email addresses of your accounts are typically not stored on the IoT Platform. In this case, you can call this API using the mapping between your proprietary account IDs and IoT Platform identityIds. You must store this mapping yourself. You can share up to 20 devices at a time. Yes. The client SDK must enable user identity authentication.

Request parameters

Parameter Type Required Description
iotIdList List< String > Yes A list of device iotIds. You can share up to 20 devices at a time.
targetIdentityId String No The ID of the target identity to share with. You must specify either the user attribute pair or the identity ID.
accountAttr String No The attribute that uniquely identifies the target user, such as a mobile number or an email address.
accountAttrType String No The type of attribute that uniquely identifies the target user, such as a mobile number or an email address. MOBILE: mobile number. EMAIL: email address.
mobileLocationCode String No The country code for the mobile number, such as 86.
autoAcceptBooleanNoSpecifies whether to automatically accept the share request. To use this parameter, you must enable the whitelist feature.

Return parameters

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c80xxxxxxx5f6f62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "accountAttr":"1365663****",
            "accountAttrType": "MOBILE",
             "iotIdList":[
                            "inqfGrp0xxxxxxxxpD00100fd600",
                            "ETytXLwjxxxxxxxx4qG0010629e00"   
                         ]
        },
        "version": "1.0"
    }
  • Successful response example
    {
       "code": 200,
       "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }        
  • Error response example
    {
     "code":2064,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"need authorize to bind"
    }           

Get the shared notification list

Definition

path Version Description Requires user identity authentication
/uc/getShareNoticeList 1.0.7 Gets the shared notification list. Yes. The client SDK must enable identity authentication.

Request parameters

Parameter Type Required Description
pageNo Int Yes The current page number. The value starts from 1.
pageSize Int Yes The number of entries per page. The maximum value is 200. If you specify a value greater than 200, the system queries 200 entries.
groupBy String No Specifies whether to get the notification list by batch. Valid values: NONE and BATCH. If you set this parameter to BATCH, only one notification is returned for shares in the same batch. The default value is NONE, which means no groupBy processing is performed.

Response parameters

Parameter Sub-key Sub-key Type Description
total - - Integer The total number on the cloud.
pageNo - - Integer The current page number.
pageSize - - IntegerPage size
data - - List<> The share list.
- initiatorAlias - String The account of the user who initiated the share, which can be a mobile number or an email address.
- receiverAlias - String The account of the user who received the share, which can be a mobile number or an email address.
- targetId - String The ID of the shared item.
Note If you query by BATCH and a batch contains multiple records, this field is not returned.
- targetType - String The type of the shared item.
- productImage - String The product image of the device.
- deviceName - String The deviceName of the device.
Note If you query by BATCH and a batch contains multiple records, this field is not returned.
- isReceiver - Integer Indicates whether the current user is the message recipient.
- gmtCreate - Long The creation time.
- gmtModified - Long The modification time.
- recordId - String The unique identifier of the share record.
Note If you query by BATCH and a batch contains multiple records, this field is not returned.
- batchId - String The share batch ID. When devices are shared in a batch, they have the same batch ID. The client can use this ID to determine if shares belong to the same batch for aggregation and display.
- status - Integer The status.
  • -1: Initialized
  • 0: Agreed
  • 1: Rejected
  • 2: Canceled
  • 3: Expired
  • 4: Preempted
  • 5: Deleted
  • 6: Initiator detached
  • 99: Abnormal
- description - String The description.
- categoryImage - String The category icon.
Note If you query by BATCH and a batch contains multiple records, this field is not returned.
- productName - String The product name.
Note If you query by BATCH and a batch contains multiple records, this field is not returned.
- batchInfo - Struct If a batch contains multiple records, this field is not empty and contains information about the batch.
- - recordCount Integer The number of share records in the current batch. For example, if 10 devices are shared in a batch, there are 10 corresponding share records.

Examples

  • Request example
    {
        "request":{
            "iotToken":"109049c80xxxxxxxx5fe29a3ba",
            "apiVer":"1.0.2"
        },
        "id":150821281****,
        "params":{
            "pageNo":1,
            "pageSize":10,
            "groupBy":"BATCH"
        },
        "version":"1.0"
    }
  • Successful response example
    {
        "code":200,
        "data":{
            "total":1,
            "pageNo":1,
            "pageSize":10,
            "data":[
                {
                    "gmtCreate":"1390000****",
                    "gmtModified":"1390000****",
                    "description":"Sharing device with 1390000****, waiting for confirmation",
                    "targetType":"DEVICE",
                    "batchId":"ACCOUNT_DEV_SHARE_3fbd910a-xxxxxx-09aabf5fe5b5",
                    "initiatorAlias":"1390000****",
                    "receiverAlias":"1390000****",
                    "isReceiver":0,
                    "status":-1,
                    "batchInfo":{
                        "recordCount":10
                    }
                }
            ]
        },
        "id":"e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
    }
  • Error response example
    {
     "code":2062,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"identityId not exist"
    }

Get the shared notification list within a batch

Description

path Version Description Requires user identity authentication
/living/user/device/shared/record/query 1.0.0 Queries device sharing records. You can query by batch ID. Yes. The client SDK must enable identity authentication.

Request parameters

Parameter Type Required Description
pageNo Int Yes The current page number. The value starts from 1.
pageSize Int Yes The number of entries per page. The maximum value is 20.
batchId String Yes The ID of the batch to query.

Response parameters

Parameter Sub-key Type Description
total - Integer The total number on the cloud.
pageNo - Integer The current page number.
pageSize - IntegerPage size
data - List<> The share list.
- initiatorAlias String The alias of the user who initiated the share.
- receiverAlias String The alias of the user who received the share.
- targetId String The ID of the shared item.
- targetType String The type of the shared item.
- productImage String The product image of the device.
- deviceName String The deviceName of the device.
- isReceiver Integer Indicates whether the current user is the message recipient.
- gmtCreate Long The creation time.
- gmtModified Long The modification time.
- recordId String The unique identifier of the share record.
- batchId String The share batch ID. When devices are shared in a batch, they have the same batch ID. The client can use this ID to determine if shares belong to the same batch for aggregation and display.
- status Integer The status.
  • -1: Initialized
  • 0: Agreed
  • 1: Rejected
  • 2: Canceled
  • 3: Expired
  • 4: Preempted
  • 5: Deleted
  • 6: Initiator detached
  • 99: Abnormal
- description StringDescription
- categoryImage String The category icon.
- productName String The product name.

Examples

  • Request example
    {
        "request":{
            "iotToken":"109049c80xxxxxxxx5fe29a3ba",
            "apiVer":"1.0.2"
        },
        "id":150821281****,
        "params":{
            "pageNo":1,
            "pageSize":10,
            "batchId":"ACCOUNT_DEV_SHARE_3fbd910a-xxxxxx-09aabf5fe5b5"
        },
        "version":"1.0"
    }
  • Successful response example
    {
        "code":200,
        "data":{
            "total":1,
            "pageNo":1,
            "pageSize":10,
            "data":[
                {
                    "gmtCreate":"1390000****",
                    "gmtModified":"1390000****",
                    "targetId":"fy2Z1oZFW********0101edf00",
                    "categoryImage":"http://xxx",
                    "description":"Sharing device with 1390000****, waiting for confirmation",
                    "targetType":"DEVICE",
                    "recordId":"a1OwEjYxxxxdfdFJNb",
                    "batchId":"ACCOUNT_DEV_SHARE_3fbd910a-xxxxxx-09aabf5fe5b5",
                    "deviceName":"b65cb59********92cd695fb",
                    "productName":"0d****195",
                    "initiatorAlias":"1390000****",
                    "receiverAlias":"1390000****",
                    "isReceiver":0,
                    "status":-1
                }
            ]
        },
        "id":"e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
    }
  • Error response example
    {
     "code":2062,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"identityId not exist"
    }

Cancel a share request as the initiator

Description

path Version Description Requires user identity authentication
/uc/cancelShare 1.0.7 The initiator cancels the share request before the recipient accepts it. Yes. The client SDK must enable identity authentication.

Request parameters

Parameter Type Required Description
recordIdList List< String > No A list of share records. You must specify either recordIdList or batchId.
batchId String No The batch ID. You must specify either recordIdList or batchId. If you specify batchId, the sharing of all devices in the batch is canceled.

Return Parameters

Examples

  • Request example
    {
        "request":{
            "iotToken":"109049c8xxxxxxxx6f62e29a3ba",
            "apiVer":"1.0.2"
        },
        "id":150821281****,
        "params":{
            "recordIdList":[
                "d4eb352adxxxxxxxx1d53febd503",
                "2568degt2xxxxxxxxe91fb61d53febd3"
            ]
        },
        "version":"1.0"
    }       
  • Successful response example
    {
       "code": 200,
       "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }
  • Error response example
    {
      "code":2093,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"forbidden to repeat cancel sharing."
    }

Accept or reject a share request as the recipient

Definition

path Version Description Requires user identity authentication
/uc/confirmShare 1.0.7 The recipient accepts or rejects the share request. Yes. The client SDK must enable identity authentication.

Request parameters

Parameter Type Required Description
recordIdList List< String > No A list of share records. You can accept or reject up to 10 share requests at a time. You must specify either recordIdList or batchId.
agree Integer Yes 0: Reject. 1: Accept.
batchId String No The batch ID. You must specify either recordIdList or batchId. If you specify batchId, you accept or reject the sharing of all devices in the batch.

Return parameters

Examples

  • Request example
    {
        "request":{
            "iotToken":"109049c80xxxxxxxxf62e29a3ba",
            "apiVer":"1.0.2"
        },
        "id":150821281****,
        "params":{
            "recordIdList":[
                "d4eb352adxxxxxxxx53febd503",
                "2568degt2xxxxxxxx91fb61d53febd3"
            ],
            "agree":1
        },
        "version":"1.0"
    }
  • Successful response example
    {
       "code": 200,
       "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }
  • Error response example
    {
     "code":2092,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"forbidden to repeat reject sharing."
    }

Set a device nickname

Definition

path Version Description Requires user identity authentication
/uc/setDeviceNickName 1.0.2 Sets a device nickname. Yes. The client SDK must enable identity authentication.

Request parameters

Parameter Type Required Description
iotId String Yes The device ID.
nickName String Yes The nickname.

Return parameters

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049cxxxxxxxxf6f62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "iotId": "5070op867xxxxxxxx49d87c207471699",
             "nickName":"nickName"
        },
        "version": "1.0"
    }    
  • Successful response example
    {
       "code": 200,
       "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }
  • Error response example
    {
      "code":2062,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"identityId not exist"
    }

Detach a user and a device

Definition

path Version Description Requires user identity authentication
/uc/unbindAccountAndDev 1.0.2 Detaches a user from a device.
  • If the user is not the owner (administrator), only that user is detached.
  • If the user is the owner (administrator), all users attached to the device are detached.
  • If the user is an administrator and the device is a gateway, the user is also detached from all of its sub-devices.
Yes. The client SDK must enable identity authentication.

Request parameters

Parameter Type Required Description
iotId String No The device ID.

Return parameters

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c8xxxxxxxx62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "iotId":"xxxx"
        },
        "version": "1.0"
    }
  • Successful response example
    {
        "code": 200,
        "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }
  • Error response example
    {
      "code":2062,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"identityId not exist"
    }

Query the relationship between a user and a device

Definition

path Version Description Requires user identity authentication
/uc/getByAccountAndDev 1.0.2 Queries the relationship between a user and a device. If no relationship exists, a null object is returned. Yes. The client SDK must enable identity authentication.

Request parameters

Parameter Type Required Description
iotId String Yes The device ID.

Response parameters

Parameter Type Description
identityId String The identity ID of the user.
iotId String The iotId of the device.
Product key String The ProductKey of the device.
deviceName String The deviceName of the device.
productName String The name of the product.
productImage String The image of the product.
productModel String The model of the product.
nickName String The nickname of the device set by the user.
netType String The network connection type of the device.
thingType String The type of the device:
  • VIRTUAL (virtual device)
  • VIRTUAL_SHADOW (virtual shadow device)
  • WEB
  • APP
  • DEVICE (regular device)
nodeTypeStringThe node type of the device: DEVICE; GATEWAY.
statusByteThe status of the device. 0: inactive. 1: online. 3: offline. 8: disabled.
ownedByte0: sharer. 1: owner.
identityAliasStringThe display name of the user: mobile, loginName, or email.
gmtModifiedDateThe time when the attachment was modified.

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c80xxxxxxxx6f62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "iotId":"xxxx"
        },
        "version": "1.0"
    }     
  • Successful response example
    {
      "code": 200,
      "data": 
        {
          "productModel": "testProduct",
          "iotId": "fy2Z1oZxxxxxxxx101edf00",
          "netType": "NET_WIFI",
          "identityId": "5082opabf51xxxxxxxx06fbdae6f6093",
          "thingType": "DEVICE",
          "nodeType": "DEVICE",
          "productKey": "a1OxxxxNb",
          "deviceName": "b65cb59e6xxxxxxxx2cd695fb",
          "productName": "0d2xxxx95",
          "status": 3
        },
      "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
    }
  • Error response example
    {
     "code":2063,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"iotId not exist"
    }

Detach a device as an administrator

Description

pathVersionDescriptionRequires user identity authentication
/uc/unbindByManager1.0.2After a user accepts a device share, an administrator can detach the specified user and device. The current logon user must be the administrator or owner of the device.Yes. The client SDK must enable identity authentication.

Request parameters

ParameterTypeRequiredDescription
targetIdentityIdStringYesThe identityId of the user who received the share (a regular member of the device), not the administrator's identityId.
iotIdListList< String>YesA list of IDs of the devices to detach.

Response parameters

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c80xxxxxxxx62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "targetIdentityId":"xxxx",
            "iotIdList":[
                            "d4eb352adxxxxxxxx1d53febd503",
                            "2568degt2xxxxxxxx91fb61d53febd3"   
                         ]
        },
        "version": "1.0"
    }
  • Successful response example
    {
        "code": 200,
        "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }        
  • Error response example
    {
     "code":2083,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"you are not the manager of some devices"
    }

Query the attachment relationships of sub-devices under a gateway

Definition

pathVersionDescriptionRequires user identity authentication
/living/device/subdevice/query1.0.0Queries the attachment relationships between sub-devices under a gateway and end users.Yes

Request parameters

ParameterTypeRequiredDescription
iotIdStringNoThe device ID. This is the unique identifier issued to the device by the IoT Platform.
productKeyStringNoThe ProductKey. This is part of the device certificate information. It is the globally unique identifier that the IoT Platform issues to the product when it is created.
deviceNameStringNoThe device name.
pageNoIntegerYesThe page number. The value starts from 1.
pageSizeIntegerYesThe number of entries per page. Valid values: 1 to 20.
langStringYesThe language. zh-CN: Chinese. en-US: English.

Response parameters

ParameterSub-parameterTypeDescription
total-LongThe total number of devices that meet the criteria.
pageNo-IntegerThe page number.
pageSize-IntegerThe number of entries per page.
data-JSONArrayA list of device details.
-iotIdStringThe iotId of the device. This is the unique identifier of the device.
-deviceNameStringThe name of the device.
-productKeyStringThe ProductKey of the product to which the device belongs.
-boundStringThe attachment status. 0: not attached. 1: attached.
-statusStringThe status of the device.
  • 0: inactive
  • 1: online
  • 3: offline
  • 8: disabled
-nickNameStringThe nickname of the device. This can be empty.

Examples

  • Request example
     {
        'id': str(uuid.uuid4()),
        'version': "1.0",
        'request': {
            'iotToken': "xxxx",
            'apiVer': "1.0.0"
        },
        'params': {
            # API parameters
            'iotId':"value1",
            'productKey':"value2",
            'deviceName':"value3",
            'pageNo':"value4",
            'pageSize':"value5",
            'lang':"value6"
        }
    }
  • Example of a successful response

    {
        "id": "4de2c367-c1db-xxxx-xxxx-8c585e595d92",
        "code": 200,
        "message": null,
        "localizedMsg": null,
        "data": "xxxx"
    }

    Example: Failed response

    {
        "id": "37f7e5fa-d6a5-xxxx-xxxx-5bf23dca6284",
        "code": 403,
        "message": "request forbidden.",
        "localizedMsg": "Request forbidden",
        "data": null
    }

Delete the shared message list

Definition

pathVersionDescriptionRequires user identity authentication
/uc/clearShareNoticeList1.0.2Deletes the shared message list, including all messages initiated and received by the user.Yes. The client SDK must enable identity authentication.

Request parameters

Response parameters

Examples

  • Request example
    {
        "request": {
            "iotToken": "c4b3f64xxxxxxxe7a06a3c5dcb3",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
        },
        "version": "1.0"
    }
                        
  • Successful response example
    {
        "code": 200,
        "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }    
  • Error response example
    {
     "code":2062,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"identityId not exist"
    }                

Query the sharing relationships between devices and a target user in a batch as an administrator

Definition

pathVersionDescriptionRequires user identity authentication
/living/user/device/shared/batch/get1.0.0An administrator queries the sharing relationships between devices and a target user in a batch.Yes. The client SDK must enable identity authentication.

Request parameters

ParameterZi JianTypeRequiredDescription
targetIdentityId-StringYesThe identityId of the target user. This is the unique identifier of the user.
deviceListJSONArrayYesThe list of devices. The maximum size is 50.
iotIdStringNoThe unique iotId of the device.
  • If this field is empty, the productKey and deviceName fields are required.
  • If this field is not empty, the iotId is used as the unique identifier of the device, even if the productKey and deviceName fields are configured.
productKeyStringNoThe ProductKey of the product to which the device belongs. This field is required when the iotId field is empty.
deviceNameStringNoThe name of the device. This field is required when the iotId field is empty.

Response parameters

ParameterSub-parameterTypeDescription
data-JSONArrayA list of device sharing relationship details.
-iotIdStringThe iotId of the device. This is the unique identifier of the device.
-productKeyStringThe ProductKey of the product to which the device belongs.
-deviceNameStringThe name of the device.
-sharedBooleanIndicates whether the device is shared with the target user.

Examples

  • Request example
    {
        "id":"xxx",
        "version":"1.0.0",
        "request":{
            "language":"en-US",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"xxx"
        },
        "params":{
              "targetIdentityId": "xxx",
            "deviceList":[
                {
                    "iotId":"edwB6xxxxNa000100"
                }
            ]
        }
    }
  • Successful response example
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":[
            {
                "iotId":"edwB6xxxxNa000100",
                  "productKey":"xxx",
                  "deviceName":"xxx",
                "shared":true
            }
        ]
    }

Attach a push channel

Definition

pathVersionDescriptionRequires user identity authentication
/uc/bindPushChannel1.0.2Link push channelYes. The client SDK must enable identity authentication.

Request parameters

ParameterTypeRequiredDescription
deviceIdStringYesThe deviceId of the push channel.
deviceTypeStringYesThe device type, such as iOS or ANDROID. The value is determined by the business party and the app.

Returned parameters

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c80xxxxxxxxf62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "deviceId":"xxxx",
            "deviceType":"iOS"
        },
        "version": "1.0"
    }              
  • Successful response example
    {
        "code": 200,
        "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }          
  • Error response example
    {
     "code":2062,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"identityId not exist"
    }              

Detach a push channel

Definition

pathVersionDescriptionRequires user identity authentication
/uc/unbindPushChannel1.0.2Attach a push channelYes. The client SDK must enable identity authentication.

Request parameters

ParameterTypeRequiredDescription
deviceIdStringYesThe deviceId of the push channel.

Response parameters

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c80xxxxxxxf62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "deviceId":"xxxx"
        },
        "version": "1.0"
    }        
  • Successful response example
    {
        "code": 200,
        "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
    }             
  • Error response example
    {
     "code":2062,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"identityId not exist"
    }         

Get the sub-device list of a gateway

Description

pathVersionDescriptionRequires user identity authentication
/subdevices/list1.0.2Gets a list of gateway sub-devices attached to a user.Yes. The client SDK must enable identity authentication.

Request parameters

ParameterTypeRequiredDescription
iotIdStringYesThe device ID.
pageNoIntYesThe current page number. The value starts from 1.
pageSizeIntYesThe number of entries per page. This is the maximum number of items on a single page.

Response parameters

ParameterSub-keyTypeDescription
total-IntegerThe total number on the cloud.
pageNo-IntegerThe current page number.
pageSize-IntegerPage size
data-List<>The sub-device list.
-iotIdStringThe iotId of the device.
-productKeyStringThe ProductKey of the device.
-deviceNameStringThe deviceName of the device.
-nickNameStringThe name of the product.
-imageStringThe category image.
-statusByteThe online status of the device. 0: inactive. 1: online. 3: offline. 8: disabled.

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c8xxxxxxxx6f62e29a3ba",
            "apiVer": "1.0.2"
        },
        "id": 150821281****,
        "params": {
            "iotId":"xxxxxxx",
            "pageNo":1,
            "pageSize":10
        },
        "version": "1.0"
    }        
  • Successful response example
    {
      "code": 200,
      "data": [
        {
          "iotId": "testIot",
          "productKey": "fy2Z1oZxxxxxxxx0101edf00",
          "deviceName": "NET_WIFI",
          "nickName": "xxxxxx",
          "image": "http://abc.jpg",
          "status": 0
        },
        {
          "iotId": "testIot",
          "productKey": "fy2Z1oZFxxxxxxxx00101edf00",
          "deviceName": "NExxxxFI",
          "nickName": "xxxxxx",
          "image": "http://abc.jpg",
          "status": 0
        }
      ],
      "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
    }  
  • Error response example
    {
     "code":2062,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Request error",
     "message":"identityId not exist"
    }     

Create a virtual user

Definition

pathVersionDescriptionRequires user identity authentication
/uc/virtual/user/create1.0.4Creates a virtual user under the current logon user.Yes. The client SDK must enable identity authentication.

Request parameters

ParameterTypeRequiredDescription
attrListListNoThe properties and property values of the user. If this is empty, a user with no properties is created. The property key must be one of the specified system properties.
attrList list structure
ParameterTypeRequiredDescription
attrKeyStringYesThe property key.
attrValueStringYesThe property value.

Response parameters

ParameterTypeDescription
userIdStringThe ID of the created virtual user.
attrListListThe property values of the user. This has the same meaning as the request parameter.
attrList list structure
ParameterTypeRequiredDescription
attrKeyStringYesThe property key.
attrValueStringYesThe property value.

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049xxxxxxxxf62e29a3ba",
            "apiVer": "1.0.4"
        },
        "id": 150821281****,
        "params": {
            "attrList": [
                  {
                     "attrKey":"name",
                     "attrValue":"Xiaoming"
                  }
            ]
        },
        "version": "1.0"
    }         
  • Successful response example
    {
        "code": 200,
        "message": "success",
        "data": {
            "userId":"10B6336Exxxxxxxx428F58AA5A18",
            "attrList":[
                {
                   "attrKey":"name",
                   "attrValue":"Xiao Ming"
                }
            ]
        }
    }       
  • Error response example
    {
     "code":503,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Service unavailable",
     "message":"service not available."
    }       

Delete a virtual user

Description

pathVersionDescriptionRequires user identity authentication
/uc/virtual/user/delete1.0.4Deletes a virtual user under the current logon user.Yes. The client SDK must enable identity authentication.

Request parameters

ParameterTypeRequiredDescription
virtualUserIdStringYesVirtual user ID

Response Parameters

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c80xxxxxxxxf6f62e29a3ba",
            "apiVer": "1.0.4"
        },
        "id": 150821281****,
        "params": {
               "userId":"10B633xxxxxxxx99BDD428F58AA5A18"
        },
        "version": "1.0"
    }
                        
  • Successful response example
    {
        "code": 200,
        "message": "success",
        "data": {
            "userId":"10B6336EFxxxxxxxx8F58AA5A18",
            "attrList":[
                {
                   "attrKey":"name",
                   "attrValue":"John Doe"
                }
            ]
        }
    }
  • Error response example
    {
     "code":503,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Service unavailable",
     "message":"service not available."
    }     

Update virtual user information

Definition

pathVersionDescriptionRequires user identity authentication
/uc/virtual/user/update1.0.4Updates the information of a virtual user under the current logon user.Yes. The client SDK must enable identity authentication.

Request parameters

ParameterTypeRequiredDescription
virtualUserIdStringYesThe virtual user ID.
opTypeIntegerYesThe operation type (opType) for updating properties. Only the following types are supported: 1 (ADD), 2 (UPDATE), and 3 (DELETE).
attrListListYesThe properties and property values of the user. The property key must be one of the specified system properties.

attrList list structure

ParameterTypeRequiredDescription
attrKeyStringYesThe property key.
attrValueStringYesThe property value.

Response parameters

ParameterTypeDescription
userIdStringThe ID of the created virtual user.
attrListListThe property values of the user. This has the same meaning as the request parameter.

attrList list structure

ParameterTypeRequiredDescription
attrKeyStringYesThe property key.
attrValueStringYesThe property value.

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c8xxxxxxxx6f62e29a3ba",
            "apiVer": "1.0.4"
        },
        "id": 150821281****,
        "params": {
               "userId":"10B6336EFxxxxxxxx28F58AA5A18",
               "opType":2,
               "attrList":[
                   {
                        "attrKey":"name",
                        "attrValue":"Li"
                   }
               ]
        },
        "version": "1.0"
    }         
  • Successful response example
    {
        "code": 200,
        "message": "success",
        "data": {
            "userId":"10B6336EFxxxxxxxx428F58AA5A18",
            "attrList":[
                {
                   "attrKey":"name",
                   "attrValue":"John Doe"
                }
            ]
        }
    }
  • Error response example
    {
     "code":503,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Service unavailable",
     "message":"service not available."
    }

Query the virtual user list

Description

pathVersionDescriptionRequires user identity authentication
/uc/virtual/user/list1.0.4Queries the list of virtual users under the current logon user.Yes. The client SDK must enable identity authentication.

Request parameters

ParameterTypeRequiredDescription
pageNoIntegerYesThe current page number. The value starts from 1.
pageSizeIntegerYesThe number of entries per page. This is the maximum number of items on a single page.

Response parameters

ParameterTypeDescription
totalLongThe total number of virtual users.
pageNoIntegerThe current page number.
pageSizeIntegerPage size
dataListThe virtual user list.
data list structure
ParameterTypeRequiredDescription
userIdStringYesThe virtual user ID.
attrListListYesThe properties and property values of the user. The property key must be one of the specified system properties.
attrList list structure
ParameterTypeRequiredDescription
attrKeyStringYesThe property key.
attrValueStringYesProperty Value

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049c80xxxxxxxxf62e29a3ba",
            "apiVer": "1.0.4"
        },
        "id": 150821281****,
        "params": {
               "pageNo":1,
               "pageSize":10
        },
        "version": "1.0"
    } 
  • Successful response example
    {
        "code": 200,
        "message": "success",
        "data": {
            "total":1,
            "pageNo":1,
            "pageSize":10,
            "data":[
                {
                    "userId":"10B633xxxxxxxxBDD428F58AA5A18",
                    "attrList":[
                       {
                           "attrKey":"name",
                           "attrValue":"Xiao Ming"
                       }
                    ]
                }
            ]
        }
    }    
  • Error response example
    {
     "code":503,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Service unavailable",
     "message":"service not available."
    }   

Query virtual user details

Description

pathVersionDescriptionRequires user identity authentication
/uc/virtual/user/query1.0.4Queries the details of a virtual user under the current logon user.Yes. The client SDK must enable identity authentication.

Request parameters

ParameterTypeRequiredDescription
virtualUserIdStringYesThe virtual user ID.

Response parameters

ParameterTypeRequiredDescription
userIdStringYesThe virtual user ID.
attrListListYesThe properties and property values of the user. The property key must be one of the specified system properties.
attrList list structure
ParameterTypeRequiredDescription
attrKeyStringYesThe property key.
attrValueStringYesThe property value.

Examples

  • Request example
    {
        "request": {
            "iotToken": "109049cxxxxxxxxf6f62e29a3ba",
            "apiVer": "1.0.4"
        },
        "id": 150821281****,
        "params": {
               "userId":"10B6336Exxxxxxxx428F58AA5A18"
        },
        "version": "1.0"
    }
  • Successful response example
    {
        "code": 200,
        "message": "success",
        "data": {
             "userId":"10B633xxxxxxxx28F58AA5A18",
             "attrList":[
                   {
                        "attrKey":"name",
                        "attrValue":"John Doe"
                   }
             ]
        }
    }
  • Error response example
    {
     "code":503,
     "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
     "localizedMsg":"Service unavailable",
     "message":"service not available."
    }

Virtual user attribute definition table

ParameterTypeDescription
displayNameStringDisplay name
nameStringName
genderIntegerGender (1: male. 2: female)
birthdayStringBirthday
QQStringQQ number
employeeIDStringEmployee ID
extNumStringOffice extension number
homeAddressStringHome address
companyAddressStringCompany address
companyNameStringCompany name
countryStringCountry name
regionStringRegion
avatarStringProfile picture (URL of the profile picture)