Skip to main content

Devices: vehicle, basics

6 operations at https://api.zaitrack.app. Request and response bodies are JSON with camelCase keys; ids are UUIDs; times are RFC 3339 in UTC.

A device's track is under /v1/devices/{deviceId}/track and the vehicle it is bound to under /v1/devices/{deviceId}/vehicle; both are listed on Positions and Vehicles.

Every operation needs an API key, a personal access token or an OAuth access token unless it says otherwise. An Idempotency-Key is replayed for 24 hours; see Idempotency. Errors are application/problem+json; see Errors.

The vehicle a device is bound to​

GET /v1/devices/{deviceId}/vehicle

  • Scope: vehicles:read or vehicles:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no

Path parameters: deviceId.

Request​

No body.

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
idstring
tenantIdstring
subOrgIdstringomitted when empty
vinstringomitted when empty
registrationobjectomitted when empty
registration.countrystring
registration.platestring
makestring
modelstring
yearinteger
assetClassstring
statusstring
capabilitiesarray of string
currentRegionstringomitted when empty
odometerKminteger
capacityTonsnumber
fuelTypestring
primaryDriverIdstringomitted when empty
attachedDevicesarray of string
markerIconstring
markerIconSetboolean
speedLimitKphintegermay be null
createdAtstring
updatedAtstring
versioninteger
etagstring

Example​

curl "https://api.zaitrack.app/v1/devices/$DEVICE_ID/vehicle" \
-H "Authorization: Bearer zk_test_…"

List devices​

GET /v1/devices

  • Scope: devices:read or devices:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no
Query parameterTypeNotes
tenantIdstring
statusstring
vehicleIdstring
driverIdstring
codecstring
deviceClassstring
modelstring
qstring
portablestring
pageSizestring
cursorstring

Request​

No body.

Response​

200: fields the handler writes, taken from its source.

FieldTypeNotes
itemsarray of object
items[].idstring
items[].tenantIdstring
items[].externalIdstring
items[].namestringomitted when empty
items[].modelstring
items[].manufacturerstring
items[].makerIdstringomitted when empty
items[].modelIdstringomitted when empty
items[].codecIdstring
items[].deviceClassstring
items[].statusstring
items[].firmwareVersionstringomitted when empty
items[].capabilitiesarray of stringomitted when empty
items[].hasCommandPasswordboolean
items[].simobjectomitted when empty
items[].sim.iccidstringomitted when empty
items[].sim.msisdnstringomitted when empty
items[].sim.operatorstringomitted when empty
items[].sim.apnstringomitted when empty
items[].sim.statusstringomitted when empty
items[].reportedFirmwarestringomitted when empty
items[].firmwareReportedAtstringomitted when empty
items[].portableboolean
items[].boundToobjectomitted when empty
items[].boundTo.kindstring
items[].boundTo.targetIdstring
items[].boundTo.boundAtstring
items[].createdAtstring
items[].updatedAtstring
items[].versioninteger
nextCursorstring

Example​

curl "https://api.zaitrack.app/v1/devices" \
-H "Authorization: Bearer zk_test_…"

Register a device​

POST /v1/devices

  • Scope: devices:write or devices:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: optional
  • Audited: no
  • Step-up MFA: no

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
tenantIdstring
externalIdstring
modelstring
manufacturerstring
modelIdstring
codecIdstring
deviceClassstring
firmwareVersionstringoptional
capabilitiesarray of stringoptional
commandPasswordstringoptional
simobjectoptional
sim.iccidstringoptional
sim.msisdnstringoptional
sim.operatorstringoptional
sim.apnstringoptional
sim.statusstringoptional
portablebooleanoptional

Response​

201: fields the handler writes, taken from its source.

FieldTypeNotes
idstring
tenantIdstring
externalIdstring
namestringomitted when empty
modelstring
manufacturerstring
makerIdstringomitted when empty
modelIdstringomitted when empty
codecIdstring
deviceClassstring
statusstring
firmwareVersionstringomitted when empty
capabilitiesarray of stringomitted when empty
hasCommandPasswordboolean
simobjectomitted when empty
sim.iccidstringomitted when empty
sim.msisdnstringomitted when empty
sim.operatorstringomitted when empty
sim.apnstringomitted when empty
sim.statusstringomitted when empty
reportedFirmwarestringomitted when empty
firmwareReportedAtstringomitted when empty
portableboolean
boundToobjectomitted when empty
boundTo.kindstring
boundTo.targetIdstring
boundTo.boundAtstring
createdAtstring
updatedAtstring
versioninteger

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/devices" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"tenantId": "…", "externalId": "…", "model": "…", "manufacturer": "…", "modelId": "…", "codecId": "…", "deviceClass": "…", "firmwareVersion": "…", "capabilities": [], "commandPassword": "…", "sim": {"iccid": "…", "msisdn": "…", "operator": "…", "apn": "…", "status": "…"}, "portable": false}'

Get a device​

GET /v1/devices/{id}

  • Scope: devices:read or devices:*
  • Rate class: read (100 per second and 360,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no

Path parameters: id.

Request​

No body.

Response​

200: fields the handler writes, taken from its source.

The same fields as the response of Register a device.

Example​

curl "https://api.zaitrack.app/v1/devices/$ID" \
-H "Authorization: Bearer zk_test_…"

Update a device (If-Match version)​

PATCH /v1/devices/{id}

  • Scope: devices:write or devices:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: not used
  • Audited: no
  • Step-up MFA: no
  • If-Match: the version you read; a stale one is refused (412 or 409)

Path parameters: id.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
externalIdstringoptional
modelstringoptional
manufacturerstringoptional
modelIdstringoptional
codecIdstringoptional
deviceClassstringoptional
firmwareVersionstringoptional
commandPasswordstringoptional
simobjectoptional
sim.iccidstringoptional
sim.msisdnstringoptional
sim.operatorstringoptional
sim.apnstringoptional
sim.statusstringoptional
portablebooleanoptional

Response​

200: fields the handler writes, taken from its source.

The same fields as the response of Register a device.

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X PATCH "https://api.zaitrack.app/v1/devices/$ID" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "3"' \
-H "Content-Type: application/json" \
-d '{"externalId": "…", "model": "…"}'

Activate a device​

POST /v1/devices/{id}:activate

  • Scope: devices:write or devices:*
  • Rate class: write (50 per second and 36,000 per hour)
  • Idempotency-Key: optional
  • Audited: no
  • Step-up MFA: no

Path parameters: id.

Request​

Fields the handler reads, taken from its source.

FieldTypeNotes
provisioningTokenstringoptional

Response​

200: fields the handler writes, taken from its source.

The same fields as the response of Register a device.

Example​

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/devices/$ID:activate" \
-H "Authorization: Bearer zk_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"provisioningToken": "…"}'