For the complete documentation index, see llms.txt. This page is also available as Markdown.

Managing device records and identifiers

Register and manage GPS trackers, sensors, and other hardware devices.

A device in Business Data Repository represents a physical hardware unit: a GPS tracker, sensor, beacon, or any other piece of trackable hardware. Devices hold the identifying information, such as IMEI numbers and serial numbers, that connects physical hardware to the rest of your platform data. When linked to an asset through a DEVICE-type custom field, a device lets tracking data flow from the hardware into the platform. The link works in both directions: on the asset, primaryDevice returns the primary device and customFields returns every linked device, while on the device, the asset field returns the asset it belongs to.

This guide covers the full device lifecycle: looking up the required catalog records, registering a device, managing its identifiers, creating device relations, updating device properties, and decommissioning it.

Prerequisites

You need your workspace's ID for all device operations. It comes with your access credentials and is carried in your access token. See Authentication for how tokens work and where the workspace ID comes from.

You also need IDs for two catalog records before you create a device:

  • Device type: a classification you define (for example, "GPS Tracker" or "Sensor")

  • Device model: the specific hardware model taken from the read-only model catalog

To check what device types already exist in your workspace, run this query:

query GetDeviceTypes {
  bdr {
    deviceTypes(workspaceId: "7c9e6679-7425-40de-944b-e07fc1f90ae7") {
      nodes { id title code }
    }
  }
}

If no device types exist yet, create the ones you need:

Device statuses are system-managed. Three built-in statuses (Not Activated, Active, and Inactive) are provided by the platform and available in every workspace. Every new device starts with Not Activated. Query deviceStatuses to get their IDs for use in filters. You can also create additional custom statuses alongside the built-in ones.

To look up a hardware model, query the read-only model catalog. You can filter by title or vendor:

If you want to browse models by manufacturer first, use the deviceVendors query to get vendor IDs, then filter deviceModels by them using filter.vendorIds.

Save the returned IDs. You'll need both to create a device.

How devices work

Device identifiers

Each device can have one or more hardware identifiers that connect the platform record to the physical hardware. Telematics servers and other systems use these identifiers to look up a device.

The available identifier types are defined by the DeviceIdType enum:

Type
Description

IMEI

15-digit International Mobile Equipment Identity

SERIAL_NUMBER

Manufacturer-assigned serial number

MAC_ADDRESS

Network interface MAC address

GUID

GUID/UUID identifier

MEID_HEX

Mobile Equipment Identifier, hexadecimal format

MEID_DEC

Mobile Equipment Identifier, decimal format

CUSTOM

Workspace-defined identifier

An identifier must be unique. Uniqueness is checked on the combination of type, value, and namespace, and the value comparison is case-insensitive. For standard hardware identifier types (IMEI, SERIAL_NUMBER, MAC_ADDRESS, etc.), namespace is always null, so the value must be unique across the entire platform. For CUSTOM identifiers, you can set a namespace string to limit where the value must be unique: two devices can share the same custom value as long as their namespaces differ. This is useful when integrating with external systems that have their own ID schemes and whose values may overlap.

Device status and properties

Devices don't support custom fields. The only properties you can change are title and modelId. Device status is controlled by the platform: every new device starts with the system status Not Activated. The platform provides three built-in statuses (Not Activated, Active, Inactive) visible to all workspaces. You can create additional custom statuses with deviceStatusCreate, but status cannot be changed through the public API.

The asset field returns the linked asset as a full Asset object, so you can query any of its fields directly, or null if the device isn't assigned to any asset. This is the same link seen from the device side: assets link to devices through custom fields of type DEVICE, and Device.asset follows that link back. The link is managed entirely from the asset side. See Creating assets and assigning devices for details.

Device relations

Two devices can be linked with a typed relation. Relation types are system-defined, so your workspace can't create new ones. To see what types are available, use the deviceRelationTypes query:

A relation has two endpoints: first and second. On the device the relation was created from (first), the relation appears in relationsFrom. On the device at the other end (second), the same relation appears in relationsTo. The first/second distinction only records the direction the relation was created in. The platform attaches no meaning to it, so your application decides what it means.

Example scenario: Onboarding a tracker shipment

FleetOps Ltd receives a shipment of Teltonika FMB003 GPS trackers for installation across their delivery fleet. This scenario walks through registering a device, recording its identifiers, linking it to a companion beacon, updating its status once installed, and decommissioning it at end of life.

1

Create a device

Register the first device using the type and model IDs from the prerequisites step

version is optional. If you leave it out, an update always applies, even when someone else changed the record after you last read it. Include it to catch such conflicts, as the examples in this scenario do. See Optimistic locking for details.

Run this mutation:

Identifiers are optional: a device may be registered before its hardware is known, and identifiers can be added later with deviceIdentifierAdd.

title is optional. When omitted or blank, the server generates "<vendor> <model> <identifier value>", for example "Teltonika FMB003 356307042772396". The identifier is chosen by type priority (IMEI, then SERIAL_NUMBER, then MAC_ADDRESS), falling back to the first one in the list. With no identifiers at all, the title is "<vendor> <model>". Provide an explicit title when the default isn't descriptive enough.

Response:

Save the id and version. You'll need both for later operations.

If any identifier already exists on another device, deviceCreate fails and the device is not created.

2

Add more identifiers

The IMEI was provided at creation. To register additional identifiers, such as a serial number, use deviceIdentifierAdd:

Response:

Both identifiers have namespace: null, so each value must be unique across the whole platform. Registering the same IMEI on another device returns a 409 DUPLICATE error.

To correct a mistakenly entered identifier, remove it using its id:

3

Assign device to an asset

FMB003 Unit 001 will track delivery truck DE-1049. To link the device, update the asset's DEVICE-type custom field. This example assumes the asset's type already has a custom field definition of the DEVICE type. See Defining and using custom fields for instructions on setting it up.

Response:

You can verify the link from the device side:

Each device can be linked to only one asset. Assigning a device that is already linked to a different asset fails with a validation error, unless you add reassign: true to the device value, which detaches it from the other asset and attaches it here in one step.

To unlink the device later without deleting it, use unset on the asset. That clears its primary status at the same time:

4

Create a device relation

FMB003 Unit 001 will be installed in the same vehicle as a Teltonika EYE beacon used for cargo monitoring. Link the two devices with a relation.

Start by looking up the available relation types for your workspace:

Then create the relation using the IDs of both devices and the relation type you want:

Response:

To remove the relation when the devices are separated, use deviceRelationRemove with the relation's id:

5

Update a device

When Unit 001 is installed in a delivery truck, update its title to reflect the assignment. You can also update the model in the same mutation.

Response:

Providing version turns on optimistic locking: if the device changed since you last fetched it, the API returns a 409 Conflict error instead of overwriting the change without warning. Without version, the update always applies. See Handling version conflicts for details.

Listing devices

To list all devices in a workspace:

Filtering

Use DeviceFilter to narrow down results. Conditions across different fields are combined with AND, while multiple values within a single field are combined with OR. For the full filter reference, see Filtering and sorting.

Common filter combinations:

DeviceFilter supports the following fields:

Field
Description

typeIds

One or more device type IDs

modelIds

One or more device model IDs

statusIds

One or more device status IDs

vendorIds

One or more manufacturer IDs

inventoryIds

One or more inventory IDs

titleContains

Partial, case-insensitive match on the device title

identifierContains

Partial, case-insensitive match on any identifier value

identifierContains is particularly useful for looking up a device by a partial IMEI or serial number:

Handling version conflicts

If you provide version in deviceUpdate or deviceDelete and the device has been modified by another request since your last fetch, the API returns a 409 CONFLICT error:

To resolve this, fetch the device again to get its current version and state, reconcile any differences with your intended changes, and retry the mutation with the updated version.

For a full explanation of how versioning works, see Optimistic locking.

Deleting a device

When a tracker reaches end of life and needs to be permanently removed, use deviceDelete.

Deleting a device automatically detaches it from every DEVICE-type custom field that points at it, on assets and geo objects alike, in the same transaction as the delete. The one exception is a required field: if any DEVICE field holding this device is isRequired, the delete is rejected with a validation error. In that case, unlink the device first by updating the asset's custom fields:

Then delete the device:

See also

Last updated

Was this helpful?