> ## Documentation Index > Fetch the complete documentation index at: https://developer.firstbasedev.com/llms.txt > Use this file to discover all available pages before exploring further. # List inventory items for the authenticated organization > Returns a paginated list of inventory items owned by the caller's organization. Supports filtering by deploy status, person, office, category, and more. Results are sorted by creation date descending by default. Deprecated deploy statuses (GIFTED, LOCKED, OUT_FOR_REPAIR) are rejected with 400. ## OpenAPI ````yaml /openapi.json get /api/v1/inventory openapi: 3.1.0 info: title: Firstbase API Specification Beta description: Integration endpoints for Firstbase version: 0.1.0 servers: - url: / description: Default security: - ApiKey: [] tags: - name: Inventory Orders description: Create and manage inventory orders - name: Shipment Notices V1 description: 'Query shipment notice orders (V1: package items expose `inventories` list)' - name: Packages description: '' - name: Categories description: Query available categories for asset creation - name: Catalog description: '' - name: New Joiners description: New joiner provisioning pipeline for the organization - name: Orders description: '' - name: People description: >- Manage the users of Firstbase for your organization. API follows the SCIM standard. externalDocs: url: https://scim.cloud/ - name: People — Lifecycle description: Offboard and reactivate users. - name: Assets description: Manage inventory assets - name: Regions V1 description: Query regions (V1) - name: Warehouses V1 description: Query warehouses (V1) - name: Brands description: Query available brands for asset creation - name: Inventory description: '' - name: Replacements description: Create and manage equipment replacements - name: Offices description: Manage and query office locations for the authenticated organization - name: Returns description: Return and Replacements paths: /api/v1/inventory: get: tags: - Inventory summary: List inventory items for the authenticated organization description: >- Returns a paginated list of inventory items owned by the caller's organization. Supports filtering by deploy status, person, office, category, and more. Results are sorted by creation date descending by default. Deprecated deploy statuses (GIFTED, LOCKED, OUT_FOR_REPAIR) are rejected with 400. operationId: listInventories parameters: - name: page in: query description: The page number to request (1 based) required: false schema: type: integer format: int32 description: The page number to request (1 based) example: 1 example: 1 - name: size in: query description: The number of results to return in a page required: false schema: type: integer format: int32 description: The number of results to return in a page example: 10 example: 10 - name: personId in: query description: Id of a person to which inventory is assigned required: false schema: type: string description: Id of a person to which inventory is assigned example: 00000000-0000-0000-0000-000000000000 example: 00000000-0000-0000-0000-000000000000 - name: warehouseId in: query description: Id of a warehouse to which inventory is assigned required: false schema: type: string description: Id of a warehouse to which inventory is assigned example: 00000000-0000-0000-0000-000000000000 example: 00000000-0000-0000-0000-000000000000 - name: officeId in: query description: Id of an office to which inventory is assigned required: false schema: type: string description: Id of an office to which inventory is assigned example: 00000000-0000-0000-0000-000000000000 example: 00000000-0000-0000-0000-000000000000 - name: categories in: query required: false schema: type: array description: The code of the categories items: type: string - name: deployStatuses in: query required: false schema: type: array description: The deployment statuses items: type: string enum: - ARCHIVED - AVAILABLE - AWAITING_ARRIVAL - DEPLOYED - GIFTED - LOCKED - ON_HOLD - OUT_FOR_REPAIR - UNAVAILABLE - VOIDED example: DEPLOYED - name: skuIds in: query required: false schema: type: array description: Ids of SKU items: type: string format: uuid - name: searchString in: query description: >- Keyword to search for - This searches the description, the name of the manufacturer, the category, the item's title, and the serial number. required: false schema: type: string description: >- Keyword to search for - This searches the description, the name of the manufacturer, the category, the item's title, and the serial number. example: Air example: Air - name: updatedAtFrom in: query description: >- UTC Date-time to filter inventory updated after (ISO-8601 without timezone) required: false schema: type: string format: date-time description: >- UTC Date-time to filter inventory updated after (ISO-8601 without timezone) example: '2007-12-03T10:15:30' example: '2007-12-03T10:15:30' - name: updatedAtTo in: query description: >- UTC Date-time to filter inventory updated before (ISO-8601 without timezone) required: false schema: type: string format: date-time description: >- UTC Date-time to filter inventory updated before (ISO-8601 without timezone) example: '2007-12-03T10:15:30' example: '2007-12-03T10:15:30' - name: assignedEmail in: query description: >- Email address of the person to which inventory is assigned. Alternative to personId — cannot be combined with personId. required: false schema: type: string description: >- Email address of the person to which inventory is assigned. Alternative to personId — cannot be combined with personId. example: employee@company.com example: employee@company.com - name: serialNumber in: query description: Filter by inventory serial numbers required: false schema: type: array description: Filter by inventory serial numbers items: type: string description: Filter by inventory serial numbers - name: vendorSku in: query description: Filter by vendor SKUs required: false schema: type: array description: Filter by vendor SKUs items: type: string description: Filter by vendor SKUs - name: sortBy in: query description: >- Field to sort by (product, skuId, createdAt, updatedAt, serialNumber, deployStatus, deployReason, assignee, condition, renewalDate, category, suppliedBy) required: false schema: type: string description: >- Field to sort by (product, skuId, createdAt, updatedAt, serialNumber, deployStatus, deployReason, assignee, condition, renewalDate, category, suppliedBy) example: product example: product - name: sortDirection in: query description: Sort direction (ASC, DESC) required: false schema: type: string description: Sort direction (ASC, DESC) example: ASC example: ASC responses: '200': description: Paginated list of inventory items content: application/json: schema: type: array items: $ref: '#/components/schemas/Inventory' '400': description: >- Bad request — invalid filter parameters or deprecated deploy status used content: application/json: schema: $ref: '#/components/schemas/PublicApiHttpErrors' '404': description: Not Found content: '*/*': schema: $ref: '#/components/schemas/PublicApiHttpErrors' '409': description: Conflict content: '*/*': schema: $ref: '#/components/schemas/PublicApiHttpErrors' components: schemas: Inventory: type: object description: >- A single inventory item (piece of equipment) belonging to the organization properties: id: type: string format: uuid description: Unique identifier for this inventory item example: ecb7e933-de1e-9830-b180-b25d1d0d296e skuId: type: string format: uuid description: The SKU (product variant) ID this inventory item is associated with example: 203a5df2-423a-43a9-bb19-1ccaf3434b91 serialNumber: type: string description: Hardware serial number of the device; null for non-serialized items example: 25f2e6ea9a imei: type: array items: type: string example: 356789012345678 deployStatus: type: string description: >- Current lifecycle state of the inventory item. DEPLOYED = assigned to a person; AVAILABLE = in a warehouse ready to ship; ARCHIVED = permanently decommissioned; UNAVAILABLE = in warehouse but not ready to ship; AWAITING_ARRIVAL = in transit to a warehouse. enum: - ARCHIVED - AVAILABLE - AWAITING_ARRIVAL - DEPLOYED - ON_HOLD - UNAVAILABLE example: ARCHIVED deployReason: type: string description: >- Reason code explaining why the item is in its current deployStatus. Required when transitioning to UNAVAILABLE or ARCHIVED; null when DEPLOYED or AVAILABLE. enum: - ASSIGNED_TO_ADMIN - AWAITING_INFORMATION - BOUGHT_OUT - DATA_HOLD - DECOMMISSIONED_BY_EMPLOYER - END_OF_USEFUL_LIFE_DESTROYED - END_OF_USEFUL_LIFE_DONATED - PENDING_FULFILLMENT - GIFTED_BY_EMPLOYER - GIFTED_BY_FIRSTBASE - IN_TRANSIT - LOCKED_APPLE_ACTIVATION - LOCKED_FMD_REPORTED_LOST_STOLEN - LOCKED_MDM - LOCKED_PIN - LOST_BY_FIRSTBASE - LOST_IN_TRANSIT - LOST_BY_WORKER - MARKED_FOR_DESTRUCTION - NA - NEVER_RECEIVED_BY_WORKER - OTHER - OUT_FOR_DESTRUCTION - OUT_FOR_REPAIR - PENDING_BUY_OUT - RECYCLING_REQUESTED - REQUIRES_CLEANING - REQUIRES_REPAIR - RETURN_IN_PROGRESS - SENT_TO_OFFICE - STOLEN - UNRESPONSIVE_WORKER - UNSUPPORTED_REGION - PERSONAL_DEVICE - PENDING_HOLD_RELEASE example: LOST_BY_WORKER condition: type: string description: Physical condition of the item (NEW or USED) enum: - NEW - USED_LIKE_NEW - USED_GOOD - USED_FAIR - USED - USED_POOR - UNUSABLE example: NEW categoryCode: type: string description: Category code of the SKU (e.g. COMPUTER, MONITOR, HEADSET) example: TSHIRT categoryNameOfSku: type: string description: Human-readable category name for the SKU example: T-shirt skuTitle: type: string description: Display title of the SKU (product variant name) example: T-shirt White - 5XL vendorCode: type: string description: Vendor/brand code for the SKU example: AWESOME_MERCHANDISE vendorSku: type: string description: Vendor-specific SKU or model identifier example: TSHRT_5XL_WHITE createdAt: type: string format: date-time description: Timestamp when this inventory item was created in Firstbase example: '2023-02-09T00:00:00' updatedAt: type: string format: date-time description: Timestamp when this inventory item was last updated example: '2023-03-02T17:39:01.650027' renewalDate: type: string format: date description: Date when this item is scheduled for renewal or replacement example: '2026-02-09' renewalDateUpdatedBy: type: string description: >- Who or what last set the renewalDate (e.g. organization policy vs. manual override) enum: - RENEWAL_DATE_ORGANIZATION_LEVEL - RENEWAL_DATE_ORGANIZATION_CATEGORY_LEVEL - RENEWAL_DATE_MANUALLY_UPDATED - CLEAR_RENEWAL_DATE_MANUALLY_SET example: RENEWAL_DATE_ORGANIZATION_LEVEL billingStartDate: type: string format: date description: Date when billing began for this inventory item example: '2026-02-09' billingEndDate: type: string format: date description: >- Date when billing ended or is scheduled to end for this inventory item example: '2028-02-09' procurementMethod: type: string description: >- Human-readable label indicating how this item was procured (e.g. via an inventory order ID) example: 'Inventory Order - #c853d81c-ba0b-4027-a394-d5586b61608c' returnOrder: $ref: '#/components/schemas/InventoryReturnInfo' description: >- Details of the return order associated with this inventory item, if a return has been initiated. assignedTo: $ref: '#/components/schemas/InventoryAssignedToInfo' description: >- Information about the person this inventory item is currently assigned to, if applicable. tags: type: array description: >- List of key-value tags attached to this inventory item for organization and filtering. items: $ref: '#/components/schemas/InventoryTag' uniqueItems: true pricing: $ref: '#/components/schemas/SimplifiedProductPriceDTO' description: Pricing details description: type: string description: Custom description for the inventory item example: Custom inventory description netsuiteInvoiceId: type: string description: NetSuite invoice ID for Firstbase-supplied inventory example: INV-123456 holdStartDate: type: string format: date description: >- Date when the machine retention hold started (set at warehouse receive). Null when no hold is active. unlockDate: type: string format: date description: >- Date when the machine retention hold expires (holdStartDate + holdPeriodDays). Null when no hold is active. itadRequested: type: boolean description: >- Whether ITAD was requested for this item. Copied from the return order item at hold-stamp time. appleBusiness: $ref: '#/components/schemas/AppleBusiness' description: >- Apple Business Manager assignment for serialized Apple inventory. Omitted for non-Apple or non-serialized items. required: - categoryCode - categoryNameOfSku - condition - createdAt - deployStatus - id - imei - skuId - skuTitle - tags - updatedAt - vendorCode - vendorSku PublicApiHttpErrors: type: object properties: errors: type: array items: $ref: '#/components/schemas/PublicApiError' required: - errors InventoryReturnInfo: type: object description: >- Return order information associated with this inventory item; null when the item has no active return order properties: id: type: string format: uuid description: Return order ID example: 371da231-5878-45b1-80a3-9113f8795c29 status: type: string description: Overall status of the return order enum: - PENDING - PROCESSING - COMPLETED - RETURN_KIT_SENT - RETURN_KIT_DELIVERED - RETURN_KIT_SENT_BACK - RECEIVED_IN_WAREHOUSE - RETURNED - NOT_RETURNED - SUBMITTED - CANCELLED - NONE - CONFIRMED - PARTIALLY_COMPLETED - NOT_COMPLETED createdAt: type: string format: date-time description: Timestamp when the return order was created returnOrderItemId: type: string format: uuid description: ID of the individual return order item for this inventory piece example: 371da231-5878-45b1-80a3-9113f8795c29 returnOrderItemStatus: type: string description: Status of this specific item within the return order enum: - PENDING - PROCESSING - COMPLETED - RETURN_KIT_SENT - RETURN_KIT_DELIVERED - RETURN_KIT_SENT_BACK - RECEIVED_IN_WAREHOUSE - RETURNED - NOT_RETURNED - SUBMITTED - CANCELLED - NONE - CONFIRMED - PARTIALLY_COMPLETED - NOT_COMPLETED retrievalMethod: description: >- How the item is being retrieved (e.g. return kit, prepaid label, or in-person drop-off) oneOf: - $ref: '#/components/schemas/InboundRetrievalInfo' - $ref: '#/components/schemas/PhysicalRetrievalInfo' - $ref: '#/components/schemas/ReturnKitRetrievalInfo' InventoryAssignedToInfo: type: object description: Details about who or what the inventory item is currently assigned to properties: id: type: string format: uuid description: ID of the person, office, or warehouse this item is assigned to example: 371da231-5878-45b1-80a3-9113f8795c29 type: type: string description: 'Type of the assignee: PERSON, OFFICE, or WAREHOUSE' enum: - PERSON - WAREHOUSE - OFFICE example: PERSON label: type: string description: >- Human-readable identifier for the assignee — email address for a person, name for an office or warehouse example: jane@example.com assignedAt: type: string format: date-time description: >- Timestamp when this item was assigned to the current assignee; null when the assignment date is unknown required: - id - label - type InventoryTag: type: object description: >- A label tag associated with an inventory item, used for grouping and filtering properties: id: type: string format: uuid description: Unique identifier for this tag example: 8e0caa73-cc71-4aa4-88eb-fca494de8e20 label: type: string description: Display label for the tag example: Engineering required: - id - label SimplifiedProductPriceDTO: type: object properties: regionCode: type: string priceOption: type: string price: type: number currencyCode: type: string discountedPrice: type: number discountPercentage: type: number required: - currencyCode - discountPercentage - discountedPrice - price - priceOption - regionCode AppleBusiness: type: object description: >- Apple Business Manager assignment status for a serialized Apple inventory item properties: assignmentStatus: type: string description: Whether the device is assigned in Apple Business Manager enum: - ASSIGNED - NOT_ASSIGNED example: ASSIGNED lastSyncTimestamp: type: string format: date-time description: >- UTC timestamp of the last successful ABM sync for this device; null when never synced example: '2026-07-01T12:00:00Z' nextSyncTimestamp: type: string format: date-time description: UTC timestamp of the next scheduled ABM full sync example: '2026-07-02T02:00:00Z' required: - assignmentStatus - nextSyncTimestamp PublicApiError: type: object properties: detail: type: string description: Human-readable description of the error example: Invalid request source: type: string description: >- Entity or field path that caused the error (for example order, shipmentNotice, or person:email) example: request required: - detail - source InboundRetrievalInfo: allOf: - $ref: '#/components/schemas/RetrievalMethodInfo' - type: object properties: id: type: string format: uuid description: Unique identifier for this retrieval method record status: type: string description: Current status of the inbound label retrieval process enum: - REQUESTED - PROCESSED - CANCELLED - LABEL_CREATED - SHIPPED - DELIVERED - SENT_BACK - ARRIVED_AT_PROCESSING_FACILITY - DELIVERY_EXCEPTION - NOT_PROCESSED - PARTIALLY_PROCESSED - SCHEDULING_PICK_UP inboundTrackingCode: type: string description: Tracking code for the inbound return shipment example: 1Z999AA10123456784 inboundTrackingLink: type: string description: URL to track the inbound return shipment updatedAt: type: string format: date-time description: Timestamp when this retrieval record was last updated description: >- Inbound label retrieval: a pre-paid shipping label is sent to the employee to pack and ship the equipment required: - id PhysicalRetrievalInfo: allOf: - $ref: '#/components/schemas/RetrievalMethodInfo' - type: object properties: id: type: string format: uuid description: Unique identifier for this retrieval method record status: type: string description: Current status of the physical retrieval process enum: - REQUESTED - PROCESSED - CANCELLED - LABEL_CREATED - SHIPPED - DELIVERED - SENT_BACK - ARRIVED_AT_PROCESSING_FACILITY - DELIVERY_EXCEPTION - NOT_PROCESSED - PARTIALLY_PROCESSED - SCHEDULING_PICK_UP updatedAt: type: string format: date-time description: Timestamp when this retrieval record was last updated description: >- Physical retrieval: the equipment is dropped off in person or collected by a courier at the employee's location required: - id ReturnKitRetrievalInfo: allOf: - $ref: '#/components/schemas/RetrievalMethodInfo' - type: object properties: id: type: string format: uuid description: Unique identifier for this retrieval method record status: type: string description: Current status of the return kit retrieval process enum: - REQUESTED - PROCESSED - CANCELLED - LABEL_CREATED - SHIPPED - DELIVERED - SENT_BACK - ARRIVED_AT_PROCESSING_FACILITY - DELIVERY_EXCEPTION - NOT_PROCESSED - PARTIALLY_PROCESSED - SCHEDULING_PICK_UP inboundTrackingCode: type: string description: >- Tracking code for the inbound shipment (kit being sent to the employee) example: 1Z999AA10123456784 inboundTrackingLink: type: string description: URL to track the inbound kit shipment outboundTrackingCode: type: string description: >- Tracking code for the outbound return shipment (equipment coming back to the warehouse) example: 1Z999AA10123456784 outboundTrackingLink: type: string description: URL to track the outbound return shipment updatedAt: type: string format: date-time description: Timestamp when this retrieval record was last updated description: >- Return kit retrieval: Firstbase ships a pre-paid return kit to the employee who packs and ships the equipment back required: - id RetrievalMethodInfo: description: >- The method used to retrieve (collect) the equipment for a return order. The `type` discriminator indicates which concrete type this is: RETURN_KIT, INBOUND_LABEL, or PHYSICAL. discriminator: propertyName: type properties: type: type: string required: - type securitySchemes: ApiKey: type: apiKey description: Prefix the value with "ApiKey" to indicate the custom authorization type name: Authorization in: header ````