Unit management

A 'Unit' is a fundamental entity created within a client's account to which the tracker is connected. Consequently, all messages transmitted by the tracker to a specific IP and port are directly associated with the unit.
The IP and port can be obtained using GET /partner/units/{id}/channel method.

When creating unit, it is essential to specify a unique ID along with an appropriate hardware ID.
In our applications, the hardware ID represents the type of device selected during unit creation. This allows the tracker to connect to the platform seamlessly. The list of all devices with their hardware IDs can be retrieved using the GET /client/hardware/devices method.

Create unit

This endpoint is used to create a unit and attach it to the account.

POST /partner/units

The mandatory field for this request:

name: (string) name of the unit.
ident: (string) identifier of the unit. Must be unique. It is typically the IMEI or ID of the tracker.
hw_id: (number) hardware ID of the unit. This value can be obtained using the GET/client/hardware/devices method.
app_id: (string) application ID:
- 5a5ca87f-7cbe-4540-ab5d-77bf4bf69884 - Ruhavik,
- 962e19f0-6b4a-4f81-a3fe-4b657689b6f9 - Petovik,
- b901da51-ce00-4af2-b978-8d0fca8ae1ea - Forguard
account_id: (number) account ID to which the unit belongs.

Request example:

curl -X 'POST' \
  'https://api.gps-trace.com/partner/units' \
  -H 'accept: application/json' \
  -H 'X-AccessToken: <your token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Unit description",
  "name": "Unit_name",
  "ident": "string",
  "hw_id": 40372386,
  "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
  "account_id": <account id>
}'

201 Response example:

{
  "data": {
    "name": "Unit_name",
    "device_type_id": 725,
    "cid": number,
    "protocol_id": 13,
    "channel_id": number,
    "id": number,
    "hw_id": number,
    "tls": false,
    "last_active": null,
    "messages_ttl": number,
    "messages_rotate": number,
    "description": "123Unit description",
    "extra_data": [],
    "tokens": {},
    "created_at": number,
    "updated_at": number,
    "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
    "b_type": null,
    "completed": null,
    "ready": null,
    "account_id": number,
    "ident": "string"
  }
}

id: (string) unit ID
cid: (string) account ID to which the unit belongs
device_type_id: (string) unit device type ID
channel_id: (string) unit channel ID
hw_id: (string) unit hardware ID
account_id: (number) related account ID
name: (string) unit name
description: (string) unit description (maximum length 100)
tls: (boolean) indicates the use of encrypted Flespi protocol
last_active: (object) description of when a new data piece is received from the connected device
messages_ttl: (number) duration for storing messages
messages_rotate: (number) number of messages to store
extra_data: (array of strings) data for displaying additional fields
tokens: (object) tokens for locator and toolbox
created_at: (number) unit creation date
updated_at: (number) unit update date
app_id: (string) application ID:
- 5a5ca87f-7cbe-4540-ab5d-77bf4bf69884 - Ruhavik,
- 962e19f0-6b4a-4f81-a3fe-4b657689b6f9 - Petovik,
- b901da51-ce00-4af2-b978-8d0fca8ae1ea - Forguard
b_type: (object) description of the unit billing type
completed: (object) indicates if the unit is configured with errors (e.g., in calcs link or plugins)
ready: (object) indicates if the unit is ready to work (True for ready, False if not all settings were done)
ident: (string) Unique unit identifier. It is typically the IMEI or ID of the tracker.

Get the list of units

This endpoint lets you get the list of units.

GET /partner/units

200 Response example:

{
  "data": [
    {
      "name": "test_unit",
      "device_type_id": 725,
      "cid": number,
      "channel_id": number,
      "id": number,
      "hw_id": 40372386,
      "tls": false,
      "last_active": null,
      "messages_ttl": number,
      "messages_rotate": number,
      "description": "Test_description",
      "extra_data": null,
      "tokens": null,
      "created_at": number,
      "updated_at": number,
"app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
      "b_type": null,
      "completed": null,
      "ready": null,
      "account_id": number,
      "ident": "string"
    },

id: Unique identifier for the unit.
cid: Account ID to which the unit belongs
device_type_id: ID representing the device type of the unit.
protocol_id: ID representing the protocol used by the unit.
channel_id: ID representing the communication channel used by the unit.
hw_id: Hardware ID of the unit.
account_id: ID of the related account.
name: Name of the unit.
description: Description of the unit (maximum length 100 characters).
tls: Boolean indicating whether the unit uses encrypted flespi protocol.
last_active: Timestamp indicating when new data was last received from the connected device (nullable).
messages_ttl: Time-to-live for messages (how long to store messages).
messages_rotate: Number of messages to store.
extra_data: Additional data for displaying additional fields. It's an array of objects with the following properties:
- value: Value of the additional field.
- icon: Icon for the additional field.
- label: Label for the additional field.
- showOnCard: An array of values indicating where to show the additional field.
tokens: Description of tokens for locator and toolbox (nullable).
created_at: Timestamp indicating when the unit was created.
updated_at: Timestamp indicating when the unit was last updated.
app_id: ID of the application to which the unit belongs. It can have one of the following enumerated values:
- 5a5ca87f-7cbe-4540-ab5d-77bf4bf69884 - Ruhavik,
- 962e19f0-6b4a-4f81-a3fe-4b657689b6f9 - Petovik,
- b901da51-ce00-4af2-b978-8d0fca8ae1ea - Forguard
b_type: Billing type of the unit (nullable).
completed: Indicates whether the unit is configured with errors. Possible values are "true" or "false" (nullable).
ready: Indicates the readiness status of the unit. Possible values are "true" or "false" (nullable).
ident: Unique identifier of the unit. It is typically the IMEI or ID of the tracker.

Get unit information by ID

This endpoint lets you get unit information by ID.

GET /partner/units/{id}

The mandatory fields for this request are as follows:

id - unit ID

200 Response example:

{
  "data": {
    "name": "My Queclink GV75",
    "device_type_id": 147,
    "cid": number,
    "channel_id": number,
    "id": number,
    "hw_id": 862684660,
    "tls": false,
    "last_active": null,
    "messages_ttl": number,
    "messages_rotate": number,
    "description": "",
    "extra_data": [
      {
        "label": "My SIM",
        "showOnCard": true,
        "value": "88888888888",
        "icon": "t-icon-telephone"
      }
    ],
    "tokens": null,
    "created_at": number,
    "updated_at": number,
    "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
    "b_type": null,
    "account_id": number,
    "ident": "string"
  }
}

id: Unique identifier for the unit.
cid: Account ID to which the unit belongs
device_type_id: ID representing the device type of the unit.
protocol_id: ID representing the protocol used by the unit.
channel_id: ID representing the communication channel used by the unit.
hw_id: Hardware ID of the unit.
account_id: ID of the related account.
name: Name of the unit.
description: Description of the unit (maximum length 100 characters).
tls: Boolean indicating whether the unit uses encrypted flespi protocol.
last_active: Timestamp indicating when new data was last received from the connected device (nullable).
messages_ttl: Time-to-live for messages (how long to store messages).
messages_rotate: Number of messages to store.
extra_data: Additional data for displaying additional fields. It's an array of objects with the following properties:
- value: Value of the additional field.
- icon: Icon for the additional field.
- label: Label for the additional field.
- showOnCard: An array of values indicating where to show the additional field.
tokens: Description of tokens for locator and toolbox (nullable).
created_at: Timestamp indicating when the unit was created.
updated_at: Timestamp indicating when the unit was last updated.
app_id: ID of the application to which the unit belongs. It can have one of the following enumerated values:
- 5a5ca87f-7cbe-4540-ab5d-77bf4bf69884 - Ruhavik,
- 962e19f0-6b4a-4f81-a3fe-4b657689b6f9 - Petovik,
- b901da51-ce00-4af2-b978-8d0fca8ae1ea - Forguard
b_type: Billing type of the unit (nullable).
completed: Indicates whether the unit is configured with errors. Possible values are "true" or "false" (nullable).
ready: Indicates the readiness status of the unit. Possible values are "true" or "false" (nullable).
ident: Identifier of the unit. It is typically the IMEI or ID of the tracker.

Update unit by ID

This endpoint is used to update unit by ID.

PATCH /partner/units/{id}

The mandatory fields for this request are as follows:

id - unit ID

It is important to note that Ruhavik/Petovik accounts, once activated by the client, become fully owned by the client. Therefore, partners cannot update activated Ruhavik/Petovik units.

On the other hand, Forguard accounts are fully managed by the partner and do not have any restrictions on actions from the partner's side.

When using this method, you can modify the following fields:

description: this field represents the description of the unit.
name: name of the unit.
ident: unique identifier for the unit. It is typically the IMEI or ID of the tracker.
hw_id: this field represents the Hardware ID of the unit. This value can be obtained using the GET/client/hardware/devices method.
password: some types of devices require a password for connection. This is particularly relevant for devices that require authentication during the connection process.

Request example:

curl -X 'PATCH' \
  'https://api.gps-trace.com/partner/units/<unit id>' \
  -H 'accept: application/json' \
  -H 'X-AccessToken: <your token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "new_description",
  "name": "new_unit_name",
  "ident": "string",
  "hw_id": 19671936
}'

200 Response example:

{
  "data": {
    "name": "new_unit_name",
    "device_type_id": 122,
    "cid": number,
    "channel_id": number,
    "id": number,
    "hw_id": 19671936,
    "tls": false,
    "last_active": null,
    "messages_ttl": number,
    "messages_rotate": number,
    "description": "new_description",
    "extra_data": null,
    "tokens": null,
    "created_at": number,
    "updated_at": number,
    "app_id": "5a5ca87f-7cbe-4540-ab5d-77bf4bf69884",
    "b_type": null,
    "completed": null,
    "ready": null,
    "account_id": number,
    "ident": "string"
  }
}

id: (string) unit ID
cid: (string) account ID to which the unit belongs
device_type_id: (string) unit device type ID
channel_id: (string) unit channel ID
hw_id: (string) unit hardware ID
account_id: (number) related account ID
name: (string) unit name
description: (string) unit description (maximum length 100)
tls: (boolean) indicates the use of encrypted Flespi protocol
last_active: (object) description of when a new data piece is received from the connected device
messages_ttl: (number) duration for storing messages
messages_rotate: (number) number of messages to store
extra_data: (array of strings) data for displaying additional fields
tokens: (object) tokens for locator and toolbox
created_at: (number) unit creation date
updated_at: (number) unit update date
app_id: (string) application ID:
- 5a5ca87f-7cbe-4540-ab5d-77bf4bf69884 - Ruhavik,
- 962e19f0-6b4a-4f81-a3fe-4b657689b6f9 - Petovik,
- b901da51-ce00-4af2-b978-8d0fca8ae1ea - Forguard
b_type: (object) description of the unit billing type
completed: (object) indicates if the unit is configured with errors (e.g., in calcs link or plugins)
ready: (object) indicates if the unit is ready to work (True for ready, False if not all settings were done)
ident: (string) unit identifier. It is typically the IMEI or ID of the tracker.

Delete unit by ID

This endpoint allows to remove unit by ID.

It is important to note that Ruhavik/Petovik accounts, once activated by the client, become fully owned by the client. Therefore, partners cannot update activated Ruhavik/Petovik units.
On the other hand, Forguard accounts are fully managed by the partner and do not have any restrictions on actions from the partner's side.

DELETE /partner/units/{id}

id: - unit ID

Request example:

curl -X 'DELETE' \
  'https://api.gps-trace.com/partner/units/<unit id>' \
  -H 'accept: */*' \
  -H 'X-AccessToken: <your token>'

Upon successful deletion, a response with status code 200 will be returned.

Get units count

This method allows you to retrieve the count of units based on the filtering conditions specified in the request (e.g., all units, units with access to a specific application, active units or no, units of attached or unattached accounts)

GET/partner/units/count

Request body example:

curl -X 'GET' \
  'https://api.gps-trace.com/partner/units/count?ack_active=true&app_id=b901da51-ce00-4af2-b978-8d0fca8ae1ea' \
  -H 'accept: application/json' \
  -H 'X-AccessToken: <your token>'

In the provided example request, units from activated accounts (ack_active=true) in the Forguard application (app_id=b901da51-ce00-4af2-b978-8d0fca8ae1ea) are counted.

The response includes the total count of units according to the specified filter conditions.

200 Response example:

{
  "data": {
    "all": 4,
    "active": 3
  }
}

all: total count of units according to the specified filter conditions
active: the number of active units, which are those that have been connected to the platform.

Get unit messages

This method allows you to retrieve messages from a device (unit).

GET /partner/units/{id}/messages

id - unit ID

The maximum number of messages that can be retrieved is 10,000. You can also specify the number of recent messages you want to obtain.

It is important to note that Ruhavik/Petovik accounts, once activated by the client, become fully owned by the client. Therefore, partners cannot get messages from units on activated Ruhavik/Petovik accounts.

On the other hand, Forguard accounts are fully managed by the partner and do not have any restrictions on actions from the partner's side.

Request example (get the last 10 messages)

curl -X 'GET' \
  'https://api.gps-trace.com/partner/units/<unit id>/messages?count=10' \
  -H 'accept: application/json' \
  -H 'X-AccessToken: <your token>'

Example of success response:

{
  "data": [
    {
      "ain.12": 14765,
      "ain.2": 55.5867,
      "channel.id": 10664,
      "custom.0g": 16,
      "custom.battery.level": 100,
      "custom.gsm_lvl": 96,
      "custom.in1": 1,
      "custom.in5": 1,
      "custom.in6": 1,
      "custom.in7": 1,
      "custom.in8": 1,
      "custom.odo": 535.546997,
      "custom.ta": 10,
      "custom.wln_brk_max": 0.05,
      "device.id": 5459437,
      "device.name": "HG-3365",
      "device.type.id": 14,
      "engine.ignition.status": true,
      "gsm.lac": 18508,
      "gsm.mcc": 262,
      "gsm.mnc": 1,
      "ident": "string",
      "peer": "string",
      "position.altitude": 46,
      "position.direction": 320,
      "position.hdop": 1,
      "position.latitude": number,
      "position.longitude": number,
      "position.satellites": 15,
      "position.speed": 76,
      "protocol.id": 15,
      "server.timestamp": number,
      "timestamp": number
    },...
  ]
}

The fields in the response will depend on the parameters sent by the tracker.

Get telemetry data

This endpoint lets you get latest unit telemetry data.

It is important to note that Ruhavik/Petovik accounts, once activated by the client, become fully owned by the client. Therefore, partners can get information of unit messages on activated Ruhavik/Petovik accounts only if the client has enabled Service mode.

On the other hand, Forguard accounts are fully managed by the partner and do not have any restrictions on actions from the partner's side.

GET /partner/units/{id}/telemetry

id - unit ID

Request example:

curl -X 'GET' \
  'https://api.gps-trace.com/partner/units/<unit id>/telemetry' \
  -H 'accept: application/json' \
  -H 'X-AccessToken: <your token>'

200 Response example:

{
"data": {
"channel.id": {
"ts": 1713977017.812001,
"value": number
},
"device.id": {
"ts": 1713977017.812001,
"value": number
},
"device.name": {
"ts": 1713977017.812001,
"value": "string"
},
"device.type.id": {
"ts": 1713977017.812001,
"value": number
},
"ident": {
"ts": 1713977017.812001,
"value": "string"
},
"position.altitude": {
"ts": 1713977016,
"value": number
},
"position.direction": {
"ts": 1713977016,
"value": number
},
"position.latitude": {
"ts": 1713977016,
"value": number
},
"position.longitude": {
"ts": 1713977016,
"value": number
},
"position.satellites": {
"ts": 1713977016,
"value": number
},
"position.speed": {
"ts": 1713977016,
"value": number
},
"protocol.id": {
"ts": 1713977017.812001,
"value": number
} ...
}
}

ts: timestamp. The 'ts' element is included by default in every object within the 'data' object

The fields in the response will depend on the parameters sent by the tracker.

Get unit channel data

This endpoint lets you get unit communication channel data.

It is important to note that Ruhavik/Petovik accounts, once activated by the client, become fully owned by the client. Therefore, partners get information of unit channel data on activated Ruhavik/Petovik accounts only if the client has enabled Service mode.

On the other hand, Forguard accounts are fully managed by the partner and do not have any restrictions on actions from the partner's side.

GET /partner/units/{id}/channel

id - unit ID

Request example:

curl -X 'GET' \
  'https://api.gps-trace.com/partner/units/<unit id>/channel' \
  -H 'accept: application/json' \
  -H 'X-AccessToken: <your token>'

200 Response example:

{
"data": {
"id": string,
"configuration": null,
"host": "string",
"port": "string",
"ip": "string",
"shortLink": null
}
}

id: ID of the channel.
configuration: Channel configuration.
host: Channel host.
port: Channel port.
ip: Channel IP address.
shortLink: Channel short link.