API ReferenceData APIHelp CenterCommunityDevice TutorialsSample Projects
API Reference
LoginSign up

Send data to a Variable

This endpoint sends one or more Dots to a variable in a Device

To send data to a variable of a Device please make a POST request to the following URL:

HTTP MethodURL
POSThttps://industrial.api.ubidots.com/api/v1.6/devices/<device_label>/<variable_label>/values

Where <device_label> and <variable_label> are the label of the Device and Variable, respectively, to which data will be sent to.

Headers

The "X-Auth-Token" and "Content-Type" headers are required to your request:

HeaderValueRequired?Description
X-Auth-TokenTokenYesAuthentication Token of account
Content-Typeapplication/jsonYesThe type of data of the body.

Body

An object containing keys as variable labels and Dots as values. The following objects are all valid payloads:

{
  "value": 10
}

{
  "value": 10,
  "timestamp": 1634311791000,
  "context": {
    "status": "cold"
  }
}

[
  {
    "value": 10, 
    "timestamp": 1635255765000,
    "context": {
      "status": "cold"
    }
  }, 
  {
    "value": 25, 
    "timestamp": 1635255811000,
    "context": {
      "status": "warm"
    }
  }
]

{
  "value": 1, 
  "context": {
    "lat": "6.5423", 
    "lng": "-70.5783"
  }
}

For a detailed explanation of a Dots' keys, please see here.

📘

timestamp and context

The timestamp and context parameters are optional.

🚧

Maximum length

The maximum character length for the body is 10kb

Query Parameters

You may add optional parameters to the URL of your request:

ParameterTypeDescription
timestampIntegerTimestamp in milliseconds POSIX format. When present, this timestamp will be applied to all Dots in the body unless a local timestamp is sent.
tokenStringThe token to authenticate the request.
While sending it as a query parameter is supported, we strongly recommend using the X-Auth-Token header
typeStringOptional Device Type label to be applied to the Device if the Device doesn't exist yet. Learn more
statusBooleanOptional. When set to "true" then an additional "_status" object will appear in the response, containing the IDs of the device and variables, as well as a "new" field indicating whether they were just created or not. Example:
{ "_status": { "_datasource": { "id": "61d8a6731d84726e96dba805", "new": false }, "temperature": { "id": "61d8a6751d84726d00e5b7b8", "new": true } }, ... }

Examples

Send a single value to a variable:
Update a variable and let Ubidots apply a timestamp equal to the reception time

$ curl -X POST 'https://industrial.api.ubidots.com/api/v1.6/devices/<device_label>/<variable_label>/values' \
 -H 'Content-Type: application/json' \
 -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \
 -d '{"value": 10}'

{
  "context":{},
  "created_at":1635256409897,
  "timestamp":1635256409897,
  "value":10.0
}

{
  "code":400001,
  "message":"The payload sent is not a valid json document."
}

{
  "code":401001,
  "message":"Authentication credentials were not provided."
}

Send multiple values to a variable:
Update a variable with multiple Dots, each must have its own timestamp.

$ curl -X POST 'https://industrial.api.ubidots.com/api/v1.6/devices/<device_label>/<variable_label>/values' \
 -H 'Content-Type: application/json' \
 -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \
 -d '[
  {"value": 10, "timestamp": 1635255765000}, 
  {"value": 20, "timestamp": 1635255811000}
]'

{
  "temperature":[{"status_code":201}],
  "humidity":[{"status_code":201}]
}

{
  "code":400001,
  "message":"The payload sent is not a valid json document."
}

{
  "code":401001,
  "message":"Authentication credentials were not provided."
}

Send location data:
This will update a position variable so that the Device displays its location

curl -X POST 'https://industrial.api.ubidots.com/api/v1.6/devices/<device_label>/position/values' \
 -H 'Content-Type: application/json' \
 -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \
 -d '{"value": 1, "context": {"lat": 6.5467, "lng": -76.8765}}'

{
  "context": {"lat": 6.5467, "lng": -76.8765},
  "created_at": 1635256962165,
  "timestamp": 1635256962165, 
  "value":1.0
}

{
  "code": 400001,
  "message": "The payload sent is not a valid json document."
}

{
  "code": 401001,
  "message": "Authentication credentials were not provided."
}