Devices
Complete reference for devices: register GPS trackers and sensors, manage hardware identifiers, link devices to assets, and track relations.
Devices are GPS trackers, sensors, and other hardware that collect and transmit location and telemetry data.
Queries
deviceTypes
Lists device types in the caller's workspace.
deviceTypes(
filter: CatalogItemFilter
first: Int
after: String
last: Int
before: String
orderBy: CatalogItemOrder = { field: ORDER, direction: ASC }
): DeviceTypeConnection!Arguments
filter
CatalogItemFilter
Filtering options for the returned device types.
orderBy
CatalogItemOrder
The ordering options for the returned device types.
Input types:
Output types:
deviceStatuses
Lists device statuses in the caller's workspace.
Arguments
filter
CatalogItemFilter
Filtering options for the returned device statuses.
orderBy
CatalogItemOrder
The ordering options for the returned device statuses.
Input types:
Output types:
deviceModels
Lists device models with optional vendor filter.
Arguments
filter
DeviceModelFilter
Filtering options for the returned device models.
orderBy
CatalogItemOrder
The ordering options for the returned device models.
Input types:
Output types:
deviceVendors
Lists device vendors in the caller's workspace.
Arguments
filter
CatalogItemFilter
Filtering options for the returned device vendors.
orderBy
CatalogItemOrder
The ordering options for the returned device vendors.
Input types:
Output types:
deviceRelationTypes
Lists device relation types in the caller's workspace.
Arguments
filter
CatalogItemFilter
Filtering options for the returned device relation types.
orderBy
CatalogItemOrder
The ordering options for the returned device relation types.
Input types:
Output types:
device (query)
Retrieves a device by its ID.
Arguments
id
ID!
The ID of the device to retrieve.
Output types:
devices
Lists devices in the caller's workspace.
Arguments
filter
DeviceFilter
Filtering options for the returned devices.
orderBy
DeviceOrder
The ordering options for the returned devices.
Input types:
Output types:
deviceActivationServer
The data gateway address a device of this model is pointed at: what the user enters on the device for MANUAL setup, before deviceActivate, and what the Register SMS carries for AUTOMATIC. The port is that of the model's protocol. Null while the installation publishes no address. Refused for a model that is not supported, as deviceActivate is. Needs the create right on devices.
Arguments
modelId
ID!
The device model the device is activated with. Must be supported.
Output types:
deviceActivationPhoneAvailable
Whether deviceActivate would accept this phone: no device of any workspace holds it, or the one that does is the caller's device with identifier. Lets a client check the phone before submitting the form; deviceActivate still enforces uniqueness, so a phone taken in between is refused there with DUPLICATE.
Arguments
phone
String!
The SIM phone number, as DeviceActivateInput.phone takes it: 5 to 20 digits.
identifier
String
The identifier the form activates, as DeviceActivateInput.identifier takes it. The phone of the caller's device with this identifier counts as available, since re-running activation for that device keeps it.
Mutations
deviceCreate
Creates a new device.
Arguments
input
DeviceCreateInput!
The input fields for creating the device.
Input types:
Output types:
deviceUpdate
Updates an existing device.
Arguments
input
DeviceUpdateInput!
The input fields for updating the device.
Input types:
Output types:
deviceDelete
Deletes a device.
Every DEVICE custom-field value pointing at it is detached in the same transaction, on assets and on geo objects alike, so no holder is left naming a device that is gone. A value in a field that isRequired is not detached, since that would leave its holder invalid; it refuses the delete instead.
Refused with IN_USE while another live entity points at it through one of its own fields, custom-field values and field definitions included; the error's blockers name the first five of them, and hasMoreBlockers says whether it left any out. A required DEVICE field holding the device and a live flow linking it, in a workspace that has IoT Logic, are among them; the flows of a workspace without IoT Logic block nothing. Nothing is detached when the delete is refused.
Arguments
input
DeviceDeleteInput!
The input fields for deleting the device.
Input types:
Output types:
deviceIdentifierAdd
Adds an identifier to a device.
Not an idempotent command: DUPLICATE when an identifier with the same type, value and namespace already exists — the uniqueness scope is the whole installation, not the device, so the conflict may sit on a device the caller cannot see. A null namespace is global and collides with other null namespaces.
Arguments
input
DeviceIdentifierAddInput!
The input fields for adding the identifier.
Input types:
Output types:
deviceIdentifierRemove
Removes an identifier from a device.
Not an idempotent command: NOT_FOUND when identifierId names no identifier, including a repeat of a call that already succeeded.
Arguments
input
DeviceIdentifierRemoveInput!
The input fields for removing the identifier.
Input types:
Output types:
deviceActivate
Activates a device: creates it with the given identifier, records SIM/APN data and sets it awaiting_connection. For AUTOMATIC setup it also queues the SMS with APN and server settings; for MANUAL setup nothing is sent, and the user enters DeviceActivation.server on the device. The first frame makes it active. For an IMEI already on a not_activated or awaiting_connection device of the caller's workspace, replaces that device's activation data and model, cancels an SMS of its previous activation still waiting to be sent and, for AUTOMATIC setup, queues the SMS again; an active or inactive device is refused. A serial number already on any device is refused as DUPLICATE, whatever its status. The device is returned even when the SMS could not be queued, and activationSms says whether it was.
Arguments
input
DeviceActivateInput!
The input fields for activating the device.
Input types:
Output types:
deviceRelationCreate
Creates a relationship between devices.
Not an idempotent command: DUPLICATE when the same firstId, secondId and typeId are already related. The pair is ordered — relating A to B does not relate B to A, and creating the reverse is a second, separate relationship rather than a duplicate.
Arguments
input
DeviceRelationCreateInput!
The input fields for creating the relationship.
Input types:
Output types:
deviceRelationRemove
Removes a device relationship.
Not an idempotent command: NOT_FOUND when id names no relationship, including a repeat of a call that already succeeded.
Arguments
input
DeviceRelationRemoveInput!
The input fields for removing the relationship.
Input types:
Output types:
deviceTypeCreate
Creates a new device type.
Arguments
input
DeviceTypeCreateInput!
The input fields for creating the device type.
Input types:
Output types:
deviceTypeUpdate
Updates a device type.
Arguments
input
DeviceTypeUpdateInput!
The input fields for updating the device type.
Input types:
Output types:
deviceTypeDelete
Deletes a device type.
Refused with IN_USE while another live entity points at it through one of its own fields, custom-field values and field definitions included; the error's blockers name the first five of them, and hasMoreBlockers says whether it left any out.
Arguments
input
CatalogItemDeleteInput!
The input fields for deleting the device type.
Input types:
Output types:
deviceStatusCreate
Creates a new device status.
Arguments
input
DeviceStatusCreateInput!
The input fields for creating the device status.
Input types:
Output types:
deviceStatusUpdate
Updates a device status.
Arguments
input
DeviceStatusUpdateInput!
The input fields for updating the device status.
Input types:
Output types:
deviceStatusDelete
Deletes a device status.
Refused with IN_USE while another live entity points at it through one of its own fields, custom-field values and field definitions included; the error's blockers name the first five of them, and hasMoreBlockers says whether it left any out.
Arguments
input
CatalogItemDeleteInput!
The input fields for deleting the device status.
Input types:
Output types:
Objects
DeviceVendor
A device manufacturer or vendor.
Implements: CatalogItem, Node, Versioned, Titled
id
ID!
A globally unique identifier.
version
Int!
The version number for optimistic locking.
title
String!
The human-readable display name. Can be localized.
code
Code!
A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.
order
Int!
The display order within the same level or category.
Arguments of models
orderBy
The ordering options for the returned models. Default: { field: TITLE, direction: ASC }.
DeviceModel
A specific device model produced by a vendor.
Implements: CatalogItem, Node, Versioned, Titled
id
ID!
A globally unique identifier.
version
Int!
The version number for optimistic locking.
title
String!
The human-readable display name. Can be localized.
code
Code!
A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.
order
Int!
The display order within the same level or category.
supported
Boolean!
Whether the platform decodes this model's data.
DeviceType
A classification type for devices.
Implements: CatalogItem, Node, Versioned, Titled
id
ID!
A globally unique identifier.
version
Int!
The version number for optimistic locking.
title
String!
The human-readable display name. Can be localized.
code
Code!
A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.
order
Int!
The display order within the same level or category.
DeviceStatus
An operational status for devices.
Implements: CatalogItem, Node, Versioned, Titled
id
ID!
A globally unique identifier.
version
Int!
The version number for optimistic locking.
title
String!
The human-readable display name. Can be localized.
code
Code!
A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.
order
Int!
The display order within the same level or category.
DeviceRelationType
A type of relationship between two devices.
Implements: CatalogItem, Node, Versioned, Titled
id
ID!
A globally unique identifier.
version
Int!
The version number for optimistic locking.
title
String!
The human-readable display name. Can be localized.
code
Code!
A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.
order
Int!
The display order within the same level or category.
Device
A tracking device such as a GPS tracker, sensor, or beacon.
Implements: Node, Titled, Versioned, InventoryItem
id
ID!
A globally unique identifier. This ID is opaque and should not be parsed by clients.
version
Int!
The version number for optimistic locking. Incremented on each update. Can be provided in update/delete mutations to prevent lost updates. If omitted, the update proceeds without stale-read protection.
title
String!
The human-readable display name.
activation
SIM/APN activation data, present once the device has gone through deviceActivate. Null for a device created only via deviceCreate. Also null, with an INTERNAL_ERROR on this field alone, for a stored activation the server cannot read, such as one with a missing key; the device itself and the list it is in are served.
identifiers
[DeviceIdentifier!]!
The hardware identifiers for this device (IMEI, serial number, MAC address, etc.).
inventoryHistory
The history of inventory assignments for this device.
Arguments of inventoryHistory
orderBy
The ordering options for the returned history. Default: { field: ASSIGNED_AT direction: DESC }.
DeviceActivation
SIM/APN data recorded by deviceActivate; for AUTOMATIC setup, the Register SMS the platform sends to the device is built from it. Present once activation has run; absent for a device created only via deviceCreate. Whether the device has connected since is its status: awaiting_connection until its first frame reaches the platform, active after.
phone
String
The SIM phone number, globally unique across the installation. The activation SMS is sent to it for AUTOMATIC setup. Null for MANUAL setup activated without one.
apn
The APN settings, pushed to the device for AUTOMATIC setup. Null for MANUAL setup activated without them.
server
The data gateway address the device connects to, to be entered on the device for MANUAL setup. The port is that of the protocol of the device's model, and follows the model when it changes. Null while the installation publishes no address, and for a device whose model has no protocol the gateway knows.
ActivationServerAddress
The data gateway address a device connects to.
host
String!
The host name or IP address.
port
Int!
The TCP port.
ApnSettings
APN (Access Point Name) settings pushed to a device by the Register command.
name
String!
The APN name.
user
String
The APN username, if the carrier requires one.
DeviceIdentifier
A hardware identifier for a device.
Implements: Node
id
ID!
A globally unique identifier. This ID is opaque and should not be parsed by clients.
value
String!
The identifier value.
DeviceRelation
A relationship between two devices.
Implements: Node
id
ID!
A globally unique identifier. This ID is opaque and should not be parsed by clients.
DevicePayload
The result of a device mutation.
DeviceActivatePayload
The result of deviceActivate.
activationSms
Whether the activation SMS was queued, for AUTOMATIC setup. Null for MANUAL setup, which sends no SMS.
DeviceIdentifierPayload
The result of a device identifier mutation.
DeviceRelationPayload
The result of a device relation mutation.
DeviceTypePayload
The result of a device type mutation.
DeviceStatusPayload
The result of a device status mutation.
Inputs
DeviceFilter
Filtering options for devices.
typeIds
[ID!]
Filter by device types (OR within field).
modelIds
[ID!]
Filter by device models (OR within field).
statusIds
[ID!]
Filter by statuses (OR within field).
vendorIds
[ID!]
Filter by vendors (OR within field).
identifierContains
String
Partial match on device identifier value (case-insensitive contains).
inventoryIds
[ID!]
Filter by inventories (OR within field).
titleContains
String
Partial match on title (case-insensitive contains).
search
String
Free-text search for a device list search box: a device matches when its title or any of its identifier values contains the value (case-insensitive), or its activation SIM phone number contains it. The phone is stored as digits only, so spaces and the characters +, -, (, ) and . are dropped from the value before it is compared with the phone. So 866104 finds a device by IMEI or by phone, and +49 151 by phone. A value of only those characters still matches by title and identifier.
DeviceOrder
Ordering options for devices.
DeviceModelFilter
Filtering options for device models.
vendorIds
[ID!]
Filter by vendors (OR within field).
titleContains
String
Partial match on title (case-insensitive contains).
supported
Boolean
Filter to models the platform supports (DeviceModel.supported).
DeviceCreateInput
Input for creating a new device.
typeId
ID!
The device type ID.
modelId
ID!
The device model ID.
title
String
The device display name. If omitted or blank, the server generates "<vendor.title> <model.title> <identifier.value>" where the identifier is chosen by type priority: IMEI > SERIAL_NUMBER > MAC_ADDRESS, with fallback to identifiers[0] when none of the priority types are present. With no identifiers at all the generated title is "<vendor.title> <model.title>".
identifiers
The hardware identifiers. Optional: a device may be registered before its hardware is known. Identifiers can be added later with deviceIdentifierAdd.
inventoryId
ID
Optionally assign the new device to an existing inventory. When provided, the inventory must belong to the same workspace; the assignment is atomic with device creation (the device is not created if the assignment fails).
DeviceUpdateInput
Input for updating an existing device.
id
ID!
The device ID to update.
version
Int
The current version for optimistic locking. If omitted, auto-increments without conflict check.
modelId
ID
The new device model.
title
String
The new display name.
DeviceDeleteInput
Input for deleting a device.
id
ID!
The device ID to delete.
version
Int
The current version for optimistic locking. If omitted, auto-increments without conflict check.
DeviceIdentifierInput
Input for a device identifier.
value
String!
The identifier value. 1 to 64 Unicode code points, measured after @trim has removed leading and trailing whitespace. An astral character such as an emoji counts as one, though a UTF-16 length reports it as two. The limit is not expressible in the schema and is enforced by the server: a longer value is rejected with VALIDATION_ERROR.
DeviceIdentifierAddInput
Input for adding an identifier to a device.
deviceId
ID!
The device ID.
DeviceIdentifierRemoveInput
Input for removing an identifier from a device.
identifierId
ID!
The identifier ID to remove.
ApnSettingsInput
APN settings for deviceActivate.
name
String!
The APN name: 1-40 characters of letters, digits, ., _ or -.
user
String
The APN username, if the carrier requires one: at most 40 characters of letters, digits, ., _, - or @.
password
String
The APN password, if the carrier requires one: at most 40 characters of letters, digits, ., _, - or @. Not saved in the device activation: it goes only into the activation SMS text, which the command queue keeps with the queued command. Ignored for MANUAL setup.
DeviceActivateInput
Input for activating a device: creates it with the given identifier, records SIM/APN data, sets it awaiting_connection, and for AUTOMATIC setup queues the SMS that pushes APN and server settings to it.
modelId
ID!
The device model. Must be supported.
title
String
The device display name. For a new device, <model title> <identifier> when omitted or blank. For an existing device this activation attaches to, replaces its title when given and keeps it when omitted or blank.
identifier
String!
The identifier the model's protocol names a device by: the IMEI (15 digits) for most models, the serial number (6 to 10 digits, not all zeros, leading zeros kept) for Suntech models. Becomes the device's IMEI or SERIAL_NUMBER identifier, the serial number in the namespace of its protocol (suntech). Checked against the model: VALIDATION_ERROR on identifier otherwise.
phone
String
The SIM phone number the activation SMS is sent to: 5 to 20 digits, globally unique across the installation. Required for AUTOMATIC setup, optional for MANUAL.
apn
The APN settings pushed to the device. Required for AUTOMATIC setup, optional for MANUAL.
DeviceRelationCreateInput
Input for creating a relationship between devices.
firstId
ID!
The first device ID.
secondId
ID!
The second device ID.
typeId
ID!
The relationship type ID.
DeviceRelationRemoveInput
Input for removing a device relationship.
id
ID!
The relationship ID to remove.
DeviceTypeCreateInput
Input for creating a device type.
title
String!
The display name.
order
Int
The display order. Auto-calculated as last position if omitted.
DeviceTypeUpdateInput
Input for updating a device type.
id
ID!
The item ID to update.
version
Int
The current version for optimistic locking. If omitted, auto-increments without conflict check.
title
String
The new display name.
order
Int
The new display order.
DeviceStatusCreateInput
Input for creating a device status.
title
String!
The display name.
order
Int
The display order. Auto-calculated as last position if omitted.
DeviceStatusUpdateInput
Input for updating a device status.
id
ID!
The item ID to update.
version
Int
The current version for optimistic locking. If omitted, auto-increments without conflict check.
title
String
The new display name.
order
Int
The new display order.
Enums
DeviceIdType
The type of hardware identifier used to identify a device.
GUID
A GUID/UUID identifier.
IMEI
International Mobile Equipment Identity. A 15-digit number.
MEID_HEX
Mobile Equipment Identifier in hexadecimal format.
MEID_DEC
Mobile Equipment Identifier in decimal format.
MAC_ADDRESS
Media Access Control address of a network interface.
SERIAL_NUMBER
Manufacturer-assigned serial number.
CUSTOM
A custom identifier type defined by the workspace.
DeviceSetup
How a device activated by deviceActivate receives its server settings.
AUTOMATIC
The platform queues an SMS that pushes the APN and server settings to the device. Needs phone and apn.
MANUAL
The user enters the server settings on the device by hand, from DeviceActivation.server. No SMS is sent.
ActivationSmsOutcome
Whether deviceActivate with AUTOMATIC setup queued the SMS with the APN and server settings; some models take them in several SMS. Whether a queued SMS is sent and delivered later is not part of it. With SERVICE_UNAVAILABLE and MODEL_NOT_SUPPORTED no SMS is queued. With QUEUE_REFUSED the SMS queued before the refused one stay queued, but they do not carry all the settings. With any value but QUEUED the user enters the server settings on the device by hand, from DeviceActivation.server when it is set.
QUEUED
Every SMS is queued for sending.
SERVICE_UNAVAILABLE
The installation cannot send activation SMS.
MODEL_NOT_SUPPORTED
The platform cannot build the SMS for this device: its model or protocol has no such command, the installation publishes no server address, or the device lacks the identifier its protocol needs.
QUEUE_REFUSED
The command queue refused an SMS, for example because the queue is full. The SMS queued before it stay queued.
DeviceOrderField
Fields available for ordering devices.
TITLE
Order by title.
Pagination types
DeviceConnection
A paginated list of Device items.
Implements: Connection
DeviceEdge
An edge in the Device connection.
Implements: Edge
cursor
String!
An opaque cursor for this edge.
DeviceTypeConnection
A paginated list of DeviceType items.
Implements: Connection
DeviceTypeEdge
An edge in the DeviceType connection.
Implements: Edge
cursor
String!
An opaque cursor for this edge.
DeviceStatusConnection
A paginated list of DeviceStatus items.
Implements: Connection
DeviceStatusEdge
An edge in the DeviceStatus connection.
Implements: Edge
cursor
String!
An opaque cursor for this edge.
DeviceModelConnection
A paginated list of DeviceModel items.
Implements: Connection
DeviceModelEdge
An edge in the DeviceModel connection.
Implements: Edge
cursor
String!
An opaque cursor for this edge.
DeviceVendorConnection
A paginated list of DeviceVendor items.
Implements: Connection
DeviceVendorEdge
An edge in the DeviceVendor connection.
Implements: Edge
cursor
String!
An opaque cursor for this edge.
DeviceRelationTypeConnection
A paginated list of DeviceRelationType items.
Implements: Connection
DeviceRelationTypeEdge
An edge in the DeviceRelationType connection.
Implements: Edge
cursor
String!
An opaque cursor for this edge.
See also
Last updated
Was this helpful?