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 switching plan on Swagger.  The access key and secret required for authentication can be found by selecting "Show Access Keys" under Settings/Domain Settings


Transferring one or more Things

The endpoint for transferring a Thing is /thing/transfer

It will require 


{

  "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.


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.