Retrieve the item category tree

Operation ID: readItemCategoryTree

Group: Inventory › Item Categories

Open in the interactive reference

GET /inventory/item-categories/tree

Read-only: Reads and returns; changes nothing.

Retrieves the item category tree. Each category comes back with its parent, its depth in level, and in path the names from the top level down to the category itself. A category that has never been placed under a parent is at the top level, with level 0.

Categories are ordered by name, not by position in the tree, so build the tree from parentId.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.

Response

200 Success

Under data (readItemCategoryTreeOutput):

Field Type Required Description
data array<object> yes Every item category, each with its position in the tree, ordered by name. Example: [{"id":"a2f47b91-0c6d-4e38-95b1-7d3e6a428c50","name":"Hardware","description":"Fasteners, fittings and tooling","level":0,"path":["Hardware"],"hasChildren":true},{"id":"4e08c752-9b1f-4a63-8d20-c5f7134e9ab8","name":"Servers","parentId":"a2f47b91-0c6d-4e38-95b1-7d3e6a428c50","level":1,"path":["Hardware","Servers"],"hasChildren":true},{"id":"9d61b0af-3c58-4e17-b942-06ea8c73f215","name":"Rack","parentId":"4e08c752-9b1f-4a63-8d20-c5f7134e9ab8","level":2,"path":["Hardware","Servers","Rack"],"hasChildren":false}].
data[].id string yes The unique identifier for the item category.
data[].name string yes The display name of the category, for example 'Hardware'. Not unique: two categories can share a name, so use id to address one.
data[].description string no A free-form description of what the category covers. Absent when none was set.
data[].parentId string no The identifier of the category this one sits under. Absent for a top-level category. See id on GET inventory/item-categories/:id.
data[].level number yes The depth in the tree: 0 for a top-level category, 1 for its children, and so on, up to 5.
data[].path array<string> yes The ancestor names from the root down, ending with this category's own name. A root's path is its own name alone.
data[].hasChildren boolean yes Whether any category sits beneath this one. 
{
  "data": {
    "data": [
      {
        "id": "a2f47b91-0c6d-4e38-95b1-7d3e6a428c50",
        "name": "Hardware",
        "description": "Fasteners, fittings and tooling",
        "level": 0,
        "path": [
          "Hardware"
        ],
        "hasChildren": true
      },
      {
        "id": "4e08c752-9b1f-4a63-8d20-c5f7134e9ab8",
        "name": "Servers",
        "parentId": "a2f47b91-0c6d-4e38-95b1-7d3e6a428c50",
        "level": 1,
        "path": [
          "Hardware",
          "Servers"
        ],
        "hasChildren": true
      },
      {
        "id": "9d61b0af-3c58-4e17-b942-06ea8c73f215",
        "name": "Rack",
        "parentId": "4e08c752-9b1f-4a63-8d20-c5f7134e9ab8",
        "level": 2,
        "path": [
          "Hardware",
          "Servers",
          "Rack"
        ],
        "hasChildren": false
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Statuses