Key Concepts with the REST API
Before working with the API, it helps to understand the core Gimmal Physical data model. This section explains the key entities and how they relate to each other.
Tabs (Item Types)
A Tab is Gimmal's term for an item type — it defines a category of trackable record. Every Gimmal Physical deployment has its own set of tabs configured during implementation. Common examples include Box, File, and User.
Each tab has a numeric TabId (also called I_IT_ID), which you'll pass to most API calls. To discover what tabs are available, call GET /api/Tab. Tabs also control barcode generation rules, whether items are moveable or requestable, and whether retention schedules apply.
The first thing to do in any new integration is call GET /api/Tab to learn your TabIds. You'll need them for nearly every other endpoint.
Items, Barcodes & Locations
An Item is a single tracked record — one box, one file, one document. Every item belongs to exactly one tab (item type) and is identified by two values:
Identifier | Field | Usage |
|---|---|---|
Item ID |
| Internal numeric ID — used for GET/DELETE by ID, and for updates |
Barcode |
| Human-readable string — used for searches, transfers, and label printing |
Items exist within a containment hierarchy that can vary by deployment. For example, a Location can contain Boxes, a Box can contain a Folder, a Folder can contain a FileGrammar updated per Grammarly review. The I_CURRENT_CONTAINER_ITEM_ID field points to the item's current parent.
Note: Transferring an item changes this parent reference.
Locations are also items. In Gimmal Physical, locations (warehouses, shelves, rooms, users) are tracked as items with their own barcodes and TabIds. This is why the Transfer endpoint accepts a barcode for the location — it's referencing a location item.
Item Controller vs. SItem Controller
The API provides two controllers for item operations that offer the same functionality but use different data formats:
Item Controller ( | SItem Controller ( | |
|---|---|---|
Format | IRItem — | IRSItem — |
Payload size | Larger — includes display metadata | Compact — ~40% smaller |
Search endpoint |
|
|
Requests & Routing
A Request is a checkout workflow — someone requests an item (e.g., "deliver File X to my desk"), the request is approved or rejected, and then fulfilled by physically transferring the item.
The Request Controller manages this lifecycle.
Routing (circulation) applies to items with RoutingEnabled = true. When transferring routing-enabled items, you can specify a CirculationRoute and Comments to create an audit trail of the item's journey through a workflow (e.g., legal review → finance review → executive approval).