Devices API

The Devices API manages tracking devices in the selected database scope.

Path Structure

/[SCOPE]/devices/[COMMAND]/[DEVICE_KEY]

• SCOPE is live or sandbox.
• COMMAND is list, register, update, or delete.
• DEVICE_KEY uses the format PREFIX-NUMBER, for example RBI-123.

GET /[SCOPE]/devices/list

Returns all devices owned by the current Bearer user. Requires Authorization: Bearer ....

Response Notes

• device_token is included for owned devices.
• current_assignment contains the currently active event assignment, or false.

Response

{
  "status": {
    "code": "200",
    "apiTimeConsumed": "0.012s"
  },
  "data": [
    {
      "prefix": "RBI",
      "number": "123",
      "iccid": "",
      "imei": "123456789012345",
      "msisdn": "",
      "fota_user": "",
      "fota_pass": "",
      "base_voltage": "1000",
      "data_provider": "generic",
      "device_provider": "generic",
      "notice": "Demo device",
      "active": "1",
      "updated": "2026-05-29 12:00:00",
      "owner_user_id": "api_user",
      "device_token": "1234567890123456",
      "device_key": "RBI-123",
      "current_assignment": {
        "instance_id": 17,
        "instance_name": "Demo Event",
        "entrylist_id": 452,
        "startnumber": "42",
        "event_from": "2026-05-29 08:00:00",
        "event_to": "2026-05-30 18:00:00"
      }
    }
  ]
}

POST /[SCOPE]/devices/list/[DEVICE_KEY]

Returns one device. Requires only device_token in the payload. The response does not include device_token.

Example Request

{
  "device_token": "1234567890123456"
}

Response

{
  "status": {
    "code": "200",
    "apiTimeConsumed": "0.010s"
  },
  "data": {
    "prefix": "RBI",
    "number": "123",
    "imei": "123456789012345",
    "data_provider": "generic",
    "device_provider": "generic",
    "notice": "Demo device",
    "active": "1",
    "updated": "2026-05-29 12:00:00",
    "owner_user_id": "api_user",
    "device_key": "RBI-123",
    "current_assignment": false
  }
}

POST /[SCOPE]/devices/register

Registers a new device for the current Bearer user. Requires Authorization: Bearer ....

Required Parameters

• prefix: 1-16 letters or digits
• number: integer from 0 to 9999
• data_provider: 1-16 letters, digits, or underscore
• device_provider: 1-16 letters, digits, or underscore

Optional Parameters

• instance_id and entrylist_id: assign the device to an existing entry by stable IDs; both are required together
• instance_id and startnumber: create or reuse an entry for registration when no entrylist_id exists yet
• iccid max. 24 characters
• imei max. 15 characters
• msisdn max. 24 characters
• fota_user max. 16 characters
• fota_pass max. 16 characters
• base_voltage integer, default 1000
• notice max. 255 characters
• active 0 or 1, default 1

Example Request

{
  "prefix": "RBI",
  "number": 123,
  "data_provider": "generic",
  "device_provider": "generic",
  "imei": "123456789012345",
  "notice": "Demo device",
  "instance_id": 17,
  "startnumber": "42"
}

Response

{
  "status": {
    "code": "200",
    "apiTimeConsumed": "0.015s"
  },
  "data": {
    "device_key": "RBI-123",
    "device_token": "1234567890123456",
    "assignment": {
      "instance_id": 17,
      "entrylist_id": 452,
      "startnumber": "42"
    }
  }
}

If no assignment was requested, assignment is false.

POST /[SCOPE]/devices/update/[DEVICE_KEY]

Updates an existing device. Requires only device_token in the payload.

Optional Update Parameters

• instance_id and entrylist_id: replace the current assignment by stable IDs; both are required together
• iccid, imei, msisdn
• fota_user, fota_pass
• base_voltage, data_provider, device_provider
• notice, active

Example Request

{
  "device_token": "1234567890123456",
  "notice": "Mounted in service car",
  "active": 1,
  "instance_id": 17,
  "entrylist_id": 452
}

Response

{
  "status": {
    "code": "200",
    "apiTimeConsumed": "0.010s"
  },
  "data": {
    "device_key": "RBI-123",
    "updated": true,
    "updated_fields": [
      "notice",
      "active",
      "assignment"
    ],
    "assignment": {
      "instance_id": 17,
      "entrylist_id": 452,
      "startnumber": "42"
    }
  }
}

If no assignment was changed, assignment is false.

POST /[SCOPE]/devices/delete

Deletes multiple owned devices. Requires Authorization: Bearer ....

Example Request

{
  "devices": ["RBI-123", "RBI-124"]
}

Response

{
  "status": {
    "code": "200",
    "apiTimeConsumed": "0.009s"
  },
  "data": {
    "deleted": [
      "RBI-123",
      "RBI-124"
    ],
    "not_found": []
  }
}

POST /[SCOPE]/devices/delete/[DEVICE_KEY]

Deletes one device. Requires only device_token in the payload.

Example Request

{
  "device_token": "1234567890123456"
}

Response

{
  "status": {
    "code": "200",
    "apiTimeConsumed": "0.009s"
  },
  "data": {
    "device_key": "RBI-123",
    "deleted": true
  }
}

Errors

Errors are returned as JSON responses with an ErrorMessage field.