IoT Stock

Wearable device (band/tag) inventory management — separate from the Devices module, which covers scanners/gateways/trackers. Covers registering stock, bulk import, and assigning stock to a school. Assigning a specific item to a student happens via Students → Assign Band/Bag Tags, not here.

6 endpoint(s)

GET List Stock {{url}}/iot-stock ▸

Paginated, filterable list of wearable (band/tag) inventory — the admin dashboard's Device Stock → Wearables tab.

Query Parameters

supervisor_id (string UUID, optional): filter to stock allocated to one school.
status (string, optional): e.g. available, in_use.
assigned (boolean, optional): 1 for stock assigned to a dependant, 0 for unassigned.
batch_number / color (string, optional).
date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
search (string, optional): matches serial number or earth code.
per_page (integer, optional, max 20).

Response

Paginated stock items, plus a top-level batches array of every distinct batch_number currently in stock (for the batch filter dropdown).

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Sample Response (200 OK)

{
    "status": 200,
    "batches": [
        "BATCH-2026-01",
        "BATCH-2026-02"
    ],
    "message": "Stock fetched successfully",
    "data": [
        {
            "id": "e5f6a7b8-0000-4a11-8888-abcde1234567",
            "serial_number": "WB-10023",
            "earth_code": "EC-88231",
            "batch_number": "BATCH-2026-01",
            "color": "Blue",
            "type": "wearable_band",
            "status": "available",
            "school": null,
            "dependant": null,
            "assigned_at": null,
            "created_at": "2026-01-05 09:00:00"
        }
    ]
}

POST Add Stock Item {{url}}/iot-stock ▸

Request Body

serial_number (string, required, unique).
earth_code (string, optional, unique).
batch_number (string, optional).
color (string, optional).
type (string, optional).
administrative_id (string UUID, optional): pre-allocate the item to a school.

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Request Body

{
    "serial_number": "WB-10099",
    "earth_code": "EC-88299",
    "batch_number": "BATCH-2026-02",
    "color": "Red",
    "type": "wearable_band"
}

Sample Response (200 OK)

{
    "status": 200,
    "message": "Wearable added to stock",
    "data": {
        "id": "f6a7b8c9-0000-4a11-8888-abcde1234567",
        "serial_number": "WB-10099",
        "earth_code": "EC-88299",
        "batch_number": "BATCH-2026-02",
        "color": "Red",
        "type": "wearable_band",
        "status": "available",
        "school": null,
        "dependant": null,
        "assigned_at": null,
        "created_at": "2026-07-13 10:00:00"
    }
}

POST Bulk Add Stock {{url}}/iot-stock/bulk ▸

Request Body

items (array, required, min 1), each with:
serial_number (string, required, unique across all items and existing stock).
earthcode / batchnumber / color / type (string, all optional; type defaults to wearable_band).
administrative_id (string UUID, optional).

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Request Body

{
    "items": [
        {
            "serial_number": "WB-20001",
            "batch_number": "BATCH-2026-03",
            "color": "Green"
        },
        {
            "serial_number": "WB-20002",
            "batch_number": "BATCH-2026-03",
            "color": "Green"
        }
    ]
}

Sample Response (200 OK)

{
    "status": 200,
    "data": [],
    "message": "Bulk stock added successfully"
}

GET Get Stock Item {{url}}/iot-stock/e5f6a7b8-0000-4a11-8888-abcde1234567 ▸

Retrieve a single wearable stock item by UUID.

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Sample Response (200 OK)

{
    "status": 200,
    "message": "Stock item fetched successfully",
    "data": {
        "id": "e5f6a7b8-0000-4a11-8888-abcde1234567",
        "serial_number": "WB-10023",
        "earth_code": "EC-88231",
        "batch_number": "BATCH-2026-01",
        "color": "Blue",
        "type": "wearable_band",
        "status": "available",
        "school": null,
        "dependant": null,
        "assigned_at": null,
        "created_at": "2026-01-05 09:00:00"
    }
}

PUT Update Stock Item {{url}}/iot-stock/update/e5f6a7b8-0000-4a11-8888-abcde1234567 ▸

Update a stock item's metadata, status, or school allocation.

Request Body (all optional)

earth_code (string, unique).
batch_number / color / type (string).
status (string).
administrative_id (string UUID, nullable): reassign (or unassign, if omitted/null) the school this stock belongs to.

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Request Body

{
    "status": "available",
    "color": "Blue"
}

Sample Response (200 OK)

{
    "status": 200,
    "message": "Stock item updated successfully",
    "data": {
        "id": "e5f6a7b8-0000-4a11-8888-abcde1234567",
        "serial_number": "WB-10023",
        "earth_code": "EC-88231",
        "batch_number": "BATCH-2026-01",
        "color": "Blue",
        "type": "wearable_band",
        "status": "available",
        "school": null,
        "dependant": null,
        "assigned_at": null,
        "created_at": "2026-01-05 09:00:00"
    }
}

POST Assign Stock to School {{url}}/iot-stock/assign-to-school ▸

Bulk-assign wearable stock (by serial number) to a school. Only stock that isn't already tied up with a dependant is reassignable.

Request Body

serial_numbers (string[], required, min 1).
administrative_id (string UUID, required): the school to assign to.

Response

assigned — how many items were reassigned.
skipped — serial numbers that didn't match any reassignable stock item.

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Request Body

{
    "serial_numbers": [
        "WB-10023",
        "WB-10024"
    ],
    "administrative_id": "448e2ae4-48b4-4842-84b1-a73c84d21de1"
}

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "assigned": 2,
        "skipped": []
    },
    "message": "Assigned 2 device(s) to school successfully"
}