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:readorvehicles:* - 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.
| Field | Type | Notes |
|---|---|---|
id | string | |
tenantId | string | |
subOrgId | string | omitted when empty |
vin | string | omitted when empty |
registration | object | omitted when empty |
registration.country | string | |
registration.plate | string | |
make | string | |
model | string | |
year | integer | |
assetClass | string | |
status | string | |
capabilities | array of string | |
currentRegion | string | omitted when empty |
odometerKm | integer | |
capacityTons | number | |
fuelType | string | |
primaryDriverId | string | omitted when empty |
attachedDevices | array of string | |
markerIcon | string | |
markerIconSet | boolean | |
speedLimitKph | integer | may be null |
createdAt | string | |
updatedAt | string | |
version | integer | |
etag | string |
Example
curl "https://api.zaitrack.app/v1/devices/$DEVICE_ID/vehicle" \
-H "Authorization: Bearer zk_test_…"
List devices
GET /v1/devices
- Scope:
devices:readordevices:* - Rate class:
read(100 per second and 360,000 per hour) - Idempotency-Key: not used
- Audited: no
- Step-up MFA: no
| Query parameter | Type | Notes |
|---|---|---|
tenantId | string | |
status | string | |
vehicleId | string | |
driverId | string | |
codec | string | |
deviceClass | string | |
model | string | |
q | string | |
portable | string | |
pageSize | string | |
cursor | string |
Request
No body.
Response
200: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
items | array of object | |
items[].id | string | |
items[].tenantId | string | |
items[].externalId | string | |
items[].name | string | omitted when empty |
items[].model | string | |
items[].manufacturer | string | |
items[].makerId | string | omitted when empty |
items[].modelId | string | omitted when empty |
items[].codecId | string | |
items[].deviceClass | string | |
items[].status | string | |
items[].firmwareVersion | string | omitted when empty |
items[].capabilities | array of string | omitted when empty |
items[].hasCommandPassword | boolean | |
items[].sim | object | omitted when empty |
items[].sim.iccid | string | omitted when empty |
items[].sim.msisdn | string | omitted when empty |
items[].sim.operator | string | omitted when empty |
items[].sim.apn | string | omitted when empty |
items[].sim.status | string | omitted when empty |
items[].reportedFirmware | string | omitted when empty |
items[].firmwareReportedAt | string | omitted when empty |
items[].portable | boolean | |
items[].boundTo | object | omitted when empty |
items[].boundTo.kind | string | |
items[].boundTo.targetId | string | |
items[].boundTo.boundAt | string | |
items[].createdAt | string | |
items[].updatedAt | string | |
items[].version | integer | |
nextCursor | string |
Example
curl "https://api.zaitrack.app/v1/devices" \
-H "Authorization: Bearer zk_test_…"
Register a device
POST /v1/devices
- Scope:
devices:writeordevices:* - 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.
| Field | Type | Notes |
|---|---|---|
tenantId | string | |
externalId | string | |
model | string | |
manufacturer | string | |
modelId | string | |
codecId | string | |
deviceClass | string | |
firmwareVersion | string | optional |
capabilities | array of string | optional |
commandPassword | string | optional |
sim | object | optional |
sim.iccid | string | optional |
sim.msisdn | string | optional |
sim.operator | string | optional |
sim.apn | string | optional |
sim.status | string | optional |
portable | boolean | optional |
Response
201: fields the handler writes, taken from its source.
| Field | Type | Notes |
|---|---|---|
id | string | |
tenantId | string | |
externalId | string | |
name | string | omitted when empty |
model | string | |
manufacturer | string | |
makerId | string | omitted when empty |
modelId | string | omitted when empty |
codecId | string | |
deviceClass | string | |
status | string | |
firmwareVersion | string | omitted when empty |
capabilities | array of string | omitted when empty |
hasCommandPassword | boolean | |
sim | object | omitted when empty |
sim.iccid | string | omitted when empty |
sim.msisdn | string | omitted when empty |
sim.operator | string | omitted when empty |
sim.apn | string | omitted when empty |
sim.status | string | omitted when empty |
reportedFirmware | string | omitted when empty |
firmwareReportedAt | string | omitted when empty |
portable | boolean | |
boundTo | object | omitted when empty |
boundTo.kind | string | |
boundTo.targetId | string | |
boundTo.boundAt | string | |
createdAt | string | |
updatedAt | string | |
version | integer |
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:readordevices:* - 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:writeordevices:* - 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.
| Field | Type | Notes |
|---|---|---|
externalId | string | optional |
model | string | optional |
manufacturer | string | optional |
modelId | string | optional |
codecId | string | optional |
deviceClass | string | optional |
firmwareVersion | string | optional |
commandPassword | string | optional |
sim | object | optional |
sim.iccid | string | optional |
sim.msisdn | string | optional |
sim.operator | string | optional |
sim.apn | string | optional |
sim.status | string | optional |
portable | boolean | optional |
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:writeordevices:* - 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.
| Field | Type | Notes |
|---|---|---|
provisioningToken | string | optional |
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": "…"}'