Customer API - Transfer Thing
Thingstream provides a rich Customer API to allow you to carry out the majority of functions that can be done in the portal like transferring a Thing from a domain to a sub domain.
Here we are going to provide a guide to transferring one or more SIM Things between a domain and a sub domain.
You'll find the API documentation for transferring SIM Things on Swagger. The access key and secret required for authentication can be found by selecting "Show Access Keys" under Settings/Domain Settings
In this section
Still need help?
If you need more help or have any questions, please send an email to services-support@u-blox.com
Transferring one or more Things
The endpoint for transferring a Thing is /thing/transfer
It will require
the identities of one or more things (deviceIds)
the identity of the target domain (domainId)
the identity of the service Plan (tariffId) to be associated with the Thing in it's new domain.
{
"deviceIds": [
"string"
],
"domainId": "string",
"autoActivate": true,
"tariffId": "string"
}
Retrieve Thing identities
Thing identities are listed on the details tab of the Thing in the Thingstream customer portal or alternatively, a detailed explanation of how to use the search facility in the Thingstream Customer API in order to obtain one or more identities is available on the Customer API - Search page.
Retrieve the target domain identity
The Thingstream Customer API makes available domain details from the endpoint /auth/domain/details
Use the domain credentials of the target domain to obtain the domain identity for use in the transfer.
There is no payload and no parameters to this call as it simply gets the domain details, the response will look similar to this:
{
"ownerEmail": "demo@email.com",
"status": "ACTIVE",
"accountType": "TRIAL",
"domainName": "myorg.thingstream.io",
"id": "domain:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
The "id" field in the response wil contain the domain identity.
Retrieve the service plan identity
The Thingstream Customer API provides two endpoint from which to obtain service plan details.
/thing/tariffs/{type} returns a list of plans/tariffs by filtering on type
/thing/tariffs returns a full list of all plans/tariffs avilable to the domain
Included in the response to both are full details of each plan/tariff including it's identity. This will be returned as the 'entityId' and can take one of several forms depending on the type of Thing, mostly they will appear as follows:
"entityId": "plan:33xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
or
"entityId": "tariff:33xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
There is no request payload for this endpoint as all plans/tariffs that are applicable to the types of Things that are in your domain wil be returned.
To obtain a list of tariffs/plans available to SIM things in your domain the call would be to
/thing/tariffs/THINGSTREAM_SIM
Transfer the Thing(s)
The /thing/transfer reuquest will need to be made using the credentials of the domain in which the Thing currently exists. The tarrifId is the service plan identity retrieved in the previous section.
An example of a request payload to be used with /thing/transfer might look like this
{
"deviceIds": [
"device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
],
"domainId": "domain:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"autoActivate": true,
"tariffId": "tariff:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
The response would then confirm success or failure and provide the new device identifier as follows
{
"succeeded": [
{
"originalDeviceId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"newDeviceId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"newDeviceState": "ACTIVE",
"warnings": []
}
],
"failed": []
}
In this case the device would now be visible in the Things list of the target domain.