> For the complete documentation index, see [llms.txt](https://docs.licensespring.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.licensespring.com/license-api/device-variables/track-device-variables.md).
# Track Device Variables
Stores metadata for a specific device.
### Endpoint
* Method: `POST`
* Path: `/api/v4/track_device_variables`
* Description: Stores metadata variables for a specific device.
### Authentication
See [License API Authorization](/license-api/license-api-authorization.md).
#### Required headers
* `Date` (string) — RFC7231 GMT date string
* `Authorization` (string)
#### Recommended headers
* `Accept: application/json`
* `Content-Type: application/json`
### Request
#### Body parameters
* hardware\_id (string, required) — Unique hardware ID generated for the client device
* product (string, required) — Product short code
* variables (object, required) — JSON key-value object, with keys being variable names and values being the values to set for those variables. Values may be string, number or boolean
* license\_key (string, optional) — Required if product is key-based
* username (string, optional) — Required if product is user-based
* license\_id (number, optional) — Ensures that the action affects only the license with the specified ID. Useful if you have multiple licenses for the same product assigned to the same user.
Hints
{% hint style="info" %}
Variables are sent as a JSON object, where parameter is the variable name and value is the value of the variable, e.g.:
"variables": { "some\_variable\_name": "some value", "another\_variable\_name": "another value" }
{% endhint %}
{% hint style="danger" %}
If a variable already exists on the device, its value will be overwritten.
{% endhint %}
{% hint style="info" %}
Device variables can also be set during activation by providing a `variables` parameter in the activation payload. For examples, see: [**Activate License (Online Method)**](/license-api/license-activation-and-deactivation/activate-license-online-method.md) and [**Deactivate Bundle (Offline Method)**](/license-api/license-activation-and-deactivation/deactivate-bundle-offline-method.md).
{% endhint %}
### Schema
Request schema (TypeScript + JSON Schema)
**TypeScript**
```typescript
type TrackDeviceVariablesRequestBody = {
// required parameters:
product: string,
hardware_id: string,
variables: {
[key: string]: string | number | boolean,
}
// required for key-based products:
license_key: string,
// required for user-based products:
username: string,
}
```
**JSON Schema**
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"product": { "type": "string" },
"hardware_id": { "type": "string" },
"variables": {
"type": "object",
"additionalProperties": { "type": ["string", "number", "boolean"] }
},
"license_key": { "type": "string" },
"username": { "type": "string" },
"license_id": { "type": "number" }
},
"required": ["product", "hardware_id", "variables"],
"additionalProperties": false
}
```
Response schema (TypeScript + JSON Schema)
**TypeScript**
```typescript
type TrackDeviceVariablesResponseBody = ({
variable: string,
value: string | number | boolean,
device_id: number,
created_at: number, // UNIX Timestamp in milliseconds, e.g. 1737128752745
})[];
```
**JSON Schema**
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"variable": { "type": "string" },
"value": { "type": ["string", "number", "boolean"] },
"device_id": { "type": "number" },
"created_at": { "type": "number" }
},
"required": ["variable", "value", "device_id", "created_at"],
"additionalProperties": false
}
}
```
### Examples
{% tabs %}
{% tab title="curl" %}
```bash
curl --location --request POST '/api/v4/track_device_variables' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Date: string' \
--header 'Authorization: string' \
--data-raw '{
"hardware_id": "some-unique-id",
"product": "XY",
"license_key": "AAAA-BBBB-CCCC-DDDD",
"variables": {
"some_variable_name": "some value",
"another_variable_name": true
}
}'
```
{% endtab %}
{% tab title="nodejs" %}
```javascript
var request = require('request');
var options = {
method: 'POST',
url: '/api/v4/track_device_variables',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Date': 'string',
'Authorization': 'string'
},
body: JSON.stringify({
hardware_id: 'some-unique-id',
product: 'XY',
license_key: 'AAAA-BBBB-CCCC-DDDD',
variables: {
some_variable_name: 'some value',
another_variable_name: true
}
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
```
{% endtab %}
{% tab title="javascript (fetch)" %}
```javascript
var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Date", "string");
myHeaders.append("Authorization", "string");
var raw = JSON.stringify({
hardware_id: "some-unique-id",
product: "XY",
license_key: "AAAA-BBBB-CCCC-DDDD",
variables: {
some_variable_name: "some value",
another_variable_name: true
}
});
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};
fetch("/api/v4/track_device_variables", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
```
{% endtab %}
{% tab title="python" %}
```python
import requests
url = "/api/v4/track_device_variables"
payload = {
"hardware_id": "some-unique-id",
"product": "XY",
"license_key": "AAAA-BBBB-CCCC-DDDD",
"variables": {
"some_variable_name": "some value",
"another_variable_name": True
}
}
headers = {
"Accept": "application/json",
"Content-Type": "application/json",
"Date": "string",
"Authorization": "string"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
{% endtab %}
{% tab title="ruby" %}
```ruby
require "uri"
require "net/http"
require "json"
url = URI("/api/v4/track_device_variables")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request["Date"] = "string"
request["Authorization"] = "string"
request.body = JSON.dump({
hardware_id: "some-unique-id",
product: "XY",
license_key: "AAAA-BBBB-CCCC-DDDD",
variables: {
some_variable_name: "some value",
another_variable_name: true
}
})
response = http.request(request)
puts response.read_body
```
{% endtab %}
{% endtabs %}
### Successful and error responses
Success response example (200)
```json
[
{
"variable": "first_variable",
"value": "cooling",
"device_id": 1698663677416479,
"created_at": 1698667364802
}
]
```
Error response example (400)
```json
{
"unknown_product": "Provided product was not found",
"license_not_found": "License with the provided license user not found",
"license_not_enabled": "The license is not enabled",
"blacklisted": "This device is blacklisted",
"device_not_found": "An active device matching the hardware_id not found."
}
```
### License Authorization Method
There are two types of product licenses based on how the client application authorizes itself to interact with a license:
* Key-based product licenses: client interactions with the license have to be authorized using a `license_key`
* User-based product licenses: the license has a corresponding "license user" instead of a license key. Client interactions with the license have to be authorized using a `username`
### Errors
If an error occurs, the response will have an HTTP status code of 400 or higher, and the response body will contain an error description in the following format:
```typescript
{
status: number,
code: string,
message: string
}
```
JSON Schema
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"status": { "type": "number" },
"code": { "type": "string" },
"message": { "type": "string" }
},
"required": [
"status",
"code",
"message"
],
"additionalProperties": false
}
```
### List of exceptions
unknown_product (400)
Provided product was not found
license_not_found (400)
License with the provided license user not found
license_not_active (400)
The license is not active
license_not_enabled (400)
The license is not enabled
device_not_found (400)
An active device matching the hardware\_id not found
blacklisted (400)
This device is blacklisted
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.licensespring.com/license-api/device-variables/track-device-variables.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.