Trackonomy External API (2.2)
The Trackonomy External API lets you label and manage Trackonomy devices, decode their BLE packets, read the latest location and environmental data of tracked assets, and send integration messages from your systems.
- Label devices to activate them on the Trackonomy platform, edit labels, and look labels up:
POST,PUTandGET /external/v1/devices/label. - Deactivate devices:
POST /external/v1/devices/status. - Configure devices' firmware settings and metadata:
POST /external/v1/devices/config. - Decode Trackonomy BLE packets:
POST /external/v1/devices/{mac_id}/decodeandPOST /external/v1/devices/decode. - Read the latest location and environmental data of an asset:
GET /external/locations/{asset_id}. - Send integration messages (manifests, milestones, partner updates):
POST /external/messages.
Note: all cURL requests in this reference are examples.
| Environment | Use | Base URL | Token URL, client ID and audience |
|---|---|---|---|
| PPE | Integration testing | https://ppe.api.trackonomy.com | Issued with your PPE credentials. |
| Production | Live devices | https://api.trackonomy.com | Issued with your production credentials. |
Each environment has its own token URL, client ID, audience and credentials. A token issued for one environment is rejected by the other. Paths in this reference are appended to the base URL exactly as written.
Trackonomy issues you an API identity during onboarding, together with the token URL and audience for each environment. Request an access token from the token URL, then send it on every call as a bearer token. Cache the token until it expires, and request a new one if a call returns 401.
Use the password grant with the username, password, client ID and audience issued to you for that environment.
POST <token_url>
Content-Type: application/x-www-form-urlencoded
grant_type=password
&username=<username>
&password=<password>
&client_id=<client_id>
&audience=<audience>200 OK
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 86400
}expires_in is in seconds; the value shown is an example.
Authorization: Bearer <access_token>
Content-Type: application/jsonLabel, edit label, get labels, deactivate and configuration resolve your account from the access token, so no other identity headers are needed. If your API identity has access to more than one account, also send customer_id and authorized_group to choose one.
Decode, locations and messages take your account from the customer_id and authorized_groups headers, which each of those operations lists.
Each endpoint requires a specific permission on your API identity. Trackonomy configures these during onboarding, and they are carried in the access token. If a call returns 401 even with a fresh token, your identity may not be granted that action: contact your Trackonomy integration contact.
| Topic | Behaviour |
|---|---|
| Rate limit | Label, edit label, get labels, deactivate and configuration share one limit: 10 requests per fixed 60-second window per API identity. Requests later rejected with 400 or 401 for a missing permission also count. Over the limit returns 429 {"message": "Too many requests"}. Decode, locations and messages have no per-identity limit. Contact Trackonomy if your volume needs a higher limit. |
| Batch sizes | Label, edit label and get labels: 1 to 20 devices. Deactivate and configuration: 1 to 100 devices. Bulk decode: up to 250 packets. In label, edit label, deactivate and configuration requests a QR code may appear only once; in bulk decode each mac_id may appear only once. |
| Partial success | Multi-device calls return 207 Multi-Status when some devices succeed and others fail. errors holds one { "qrcode", "error_code" } per failed device; successful and failed are counts. 207 is also returned when every device failed, except for label: when every device fails with QRMAC_NOT_FOUND the response is 400 with the same body. An empty errors array means every device succeeded. Branch on error_code, never on message. |
| Error responses | Whole-request failures return a JSON body with message and code (429 carries only message). Validation failures return 400 {"message": "Validation failed", "code": 400, "errors": [...]} and nothing is changed. A missing, expired or wrong-environment token, a token without the required permission, a body that isn't valid JSON, or a body over 50 MB returns 401 {"message": "Unauthorized access", "code": 401}. |
| Retries | Retry 429, 500, 503 and timeouts with exponential backoff. See each operation for whether a retry is safe. |
| Idempotency: label | No idempotency key. Labelling an already-labelled device returns ALREADY_LABELLED for that device; send override: true to update its label instead. |
| Idempotency: deactivate | No idempotency key. Deactivating an already DEACTIVATED device returns ALREADY_IN_TARGET_STATE; treat it as success. |
| Request IDs | Send an optional correlation_id header on any call so Trackonomy support can trace it. |
Labelling activates a device; deactivation takes it out of service. The main states are:
| Status | Meaning | How it gets there |
|---|---|---|
NOT_ACTIVATED | Registered by Trackonomy but not labelled, so not linked to your account. | Before labelling. |
ACTIVATED | Labelled and linked to your account; its events are processed. | POST /external/v1/devices/label. |
DEACTIVATED | No longer active. | POST /external/v1/devices/status with DEACTIVATE. |
GET /external/v1/devices/label can also report FORCE_ACTIVATED, ACTIVE_WITH_NO_ALERTS, REJECTED and REUSE_OR_EXPIRED, which Trackonomy sets.
- Labelling an already-labelled device without
overridereturnsALREADY_LABELLED. DEACTIVATEsucceeds forACTIVATED,FORCE_ACTIVATEDandACTIVE_WITH_NO_ALERTSdevices. ADEACTIVATEDdevice returnsALREADY_IN_TARGET_STATE; any other status returnsINVALID_TRANSITION.- Labelling a
DEACTIVATEDdevice withoverride: trueupdates its label but does not reactivate it. This API documents no reactivation action; to reactivate a device, contact Trackonomy.