# Search items

Operation ID: `searchItems`

Group: Inventory › Items

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/searchItems)

`POST /inventory/items/search`

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches items. The filters go in the request body. The fields are the same as on GET inventory/items/:id, including standardCost, itemPurchasePrice, and currency.

missingWeight finds the items with no weight, and missingDimensions finds the items missing a length, width, or height. A landed cost's Weight or Volume allocation needs these values. The allocation also refuses a value of 0, which these filters don't find. The collection GET inventory/items cannot filter on either.

## 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`. |

## Request body

Required, `application/json`: searchItemsInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. An item must match every filter you send. Send an empty object to return all items. Example: `{"missingWeight":true}`. |
| `filters.itemCode` | string | no | Limits results to the item with this item code. The match is exact. Item codes are unique, so this matches at most one item. |
| `filters.itemTypeId` | string | no | Limits results to items with this item type. See id on GET inventory/item-types/:id. |
| `filters.categoryId` | string | no | Limits results to items in this category. See id on GET inventory/item-categories/:id. |
| `filters.unitGroupId` | string | no | Limits results to items in this unit of measure group. See id on GET inventory/unit-of-measure-groups/:id. |
| `filters.valuationMethod` | string | no | Limits results to items with this valuation method. Accepted values: 'movingAverage', 'batch', 'serials', 'none', 'fifo'. 'fifo' can be matched on read but cannot be written. |
| `filters.isBatch` | boolean | no | Limits results to items with the given isBatch value. |
| `filters.isSerial` | boolean | no | Limits results to items with the given isSerial value. |
| `filters.isInventory` | boolean | no | Limits results to items with the given isInventory value. False finds service and charge items. |
| `filters.isSalesItem` | boolean | no | Limits results to items with the given isSalesItem value. |
| `filters.isPurchaseItem` | boolean | no | Limits results to items with the given isPurchaseItem value. |
| `filters.isPerishable` | boolean | no | Limits results to items with the given isPerishable value. |
| `filters.active` | boolean | no | Limits results to items with the given active value. Omit to return both. |
| `filters.externalItemId` | string | no | Limits results to the item with this external identifier. The match is exact. |
| `filters.brandName` | string | no | Limits results to items with this brand name. The match is exact. |
| `filters.countryOfOrigin` | string | no | Limits results to items with this country of origin. The match is exact. |
| `filters.missingWeight` | boolean | no | True to return only items that have no weight, the items a landed cost Weight allocation would fail on. |
| `filters.missingDimensions` | boolean | no | True to return only items missing length, width or height, the items a landed cost Volume allocation would fail on. |
| `filters.modifiedSince` | date-time | no | Limits results to items changed on or after this time. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `page` | object | no | The pagination controls. Omit for the first page. Example: `{"size":50}`. |
| `page.cursor` | string | no | The cursor from the previous response's pagination.nextCursor. Omit for the first page. |
| `page.size` | number | no | The number of items per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

```json
{
  "filters": {
    "missingWeight": true
  },
  "page": {
    "size": 50
  }
}
```

## Response

`200` Success

Under `data` (searchItemsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The items on this page, oldest first. An empty array when nothing matches. Example: `[{"id":"517a93e4-cbb4-4571-9e3d-2343e56cfd84","itemCode":"WIDGET-01","itemName":"Standard widget","itemTypeId":"66aea173-07b8-4c4e-bc4a-5c35dedfdc16","itemTypeName":"Stocked good","categoryId":"6709e2bf-d6cf-4800-9ffa-d5a496ec4d0b","categoryName":"Components","inventoryUnitId":"77bd4c16-e1f0-426d-a98f-07b063df2d9c","inventoryUnitCode":"EA","unitGroupId":"38b5454a-c3fe-452b-9754-61f9ead49e87","unitGroupName":"Each","valuationMethod":"movingAverage","isBatch":false,"isSerial":false,"isInventory":true,"isSalesItem":true,"isPurchaseItem":true,"active":true,"weight":"1.4","weightUnit":"Kg","lastModifiedDate":"2026-08-18T09:14:22.517Z"}]`. |
| `items[].id` | string | yes | The unique identifier for the item. |
| `items[].itemCode` | string | no | The item code, for example 'WIDGET-01'. Unique within the tenant. It is set when the item is created and cannot be changed. |
| `items[].itemName` | string | no | The display name of the item. |
| `items[].externalItemId` | string | no | Your own identifier for this item in an external system. |
| `items[].brandName` | string | no | The display name of the brand. |
| `items[].notes` | string | no | Free text on the item. |
| `items[].imageAvatar` | string | no | The URL of the item's avatar image. Absent when none is set. |
| `items[].itemTypeId` | string | no | The unique identifier of the item's type. It is set when the item is created and cannot be changed. See id on GET inventory/item-types/:id. |
| `items[].itemTypeName` | string | no | The display name of the item's type. |
| `items[].categoryId` | string | no | The unique identifier of the item's category. See id on GET inventory/item-categories/:id. |
| `items[].categoryName` | string | no | The display name of the item's category. |
| `items[].inventoryUnitId` | string | no | The unique identifier of the unit stock is counted in. Every quantity on an inventory level or transaction is in this unit. See id on GET inventory/unit-of-measures/:id. |
| `items[].inventoryUnitCode` | string | no | The code of the inventory unit. |
| `items[].salesUnitId` | string | no | The unique identifier of the unit used on sales documents. Absent when it is the same as the inventory unit. See id on GET inventory/unit-of-measures/:id. |
| `items[].salesUnitCode` | string | no | The code of the sales unit. |
| `items[].purchaseUnitId` | string | no | The unique identifier of the unit used on purchase documents. Absent when it is the same as the inventory unit. See id on GET inventory/unit-of-measures/:id. |
| `items[].purchaseUnitCode` | string | no | The code of the purchase unit. |
| `items[].unitGroupId` | string | no | The unique identifier of the unit of measure group that has the conversions between the item's units. See id on GET inventory/unit-of-measure-groups/:id. |
| `items[].unitGroupName` | string | no | The display name of the unit of measure group. |
| `items[].valuationMethod` | string | no | How the item's stock is valued. Possible values: 'movingAverage', 'batch', 'serials', 'none'. 'none' is for an item that is not stocked. 'fifo' can be returned but cannot be written, because it is under development. |
| `items[].isBatch` | boolean | no | Whether the item is tracked by batch. Receipts and shipments of it name batches. |
| `items[].isSerial` | boolean | no | Whether the item is tracked by serial number. Receipts and shipments of it name one serial per unit. |
| `items[].isInventory` | boolean | no | Whether stock levels are kept for the item. False for a service or charge item. |
| `items[].isSalesItem` | boolean | no | Whether the item can appear on sales documents. |
| `items[].isPurchaseItem` | boolean | no | Whether the item can appear on purchase documents. |
| `items[].active` | boolean | no | Whether the item can be selected on new documents. False means it is retired, and historical records keep it. |
| `items[].eccnNumber` | string | no | The Export Control Classification Number. |
| `items[].htsCode` | string | no | The Harmonized Tariff Schedule code. |
| `items[].countryOfOrigin` | string | no | The country the item originates from. |
| `items[].minStockLevel` | decimal | no | The stock level below which the item should be reordered, in the inventory unit. |
| `items[].minimumTransactionQuantity` | decimal | no | The smallest quantity any document can move. Absent when there is no restriction. |
| `items[].leadTime` | decimal | no | The number of weeks between ordering the item and receiving it. |
| `items[].standardCost` | decimal | no | The standard cost carried for planning, in the item's currency. It is not the value of the stock on hand. Read that from GET inventory/inventory-levels. |
| `items[].itemPurchasePrice` | decimal | no | The expected purchase price, in the item's currency. |
| `items[].currency` | string | no | The currency of standardCost and itemPurchasePrice. Format ISO 4217, for example 'USD'. |
| `items[].weight` | decimal | no | The weight of one item, in weightUnit. A landed cost Weight allocation fails rather than falling back when an item on the receipt has none. |
| `items[].weightUnit` | string | no | The unit weight is expressed in. Possible values: 'G', 'Kg', 'Lbs'. |
| `items[].grossWeight` | decimal | no | The weight including packaging, in weightUnit. |
| `items[].netWeight` | decimal | no | The weight excluding packaging, in weightUnit. |
| `items[].length` | decimal | no | The length of one item. A landed cost Volume allocation needs length, width and height together, and fails when the set is incomplete. |
| `items[].width` | decimal | no | The width of one item. |
| `items[].height` | decimal | no | The height of one item. |
| `items[].volumePerUnit` | decimal | no | The volume of one item, in volumeUnit. |
| `items[].volumeUnit` | string | no | The unit volumePerUnit is expressed in. Possible values: 'L'. |
| `items[].defaultAllocationMode` | string | no | The allocation mode a landed cost charge for this item falls back to when it names none. Possible values: 'Equal', 'Quantity', 'LineTotal', 'Weight', 'Volume'. |
| `items[].isPerishable` | boolean | no | Whether the item expires. |
| `items[].shelfLifeDays` | number | no | The number of days the item keeps from production. |
| `items[].minShelfLifeDaysOnReceipt` | number | no | The least remaining shelf life a receipt of this item will accept. |
| `items[].minShelfLifeDaysOnDispatch` | number | no | The least remaining shelf life a dispatch of this item will accept. |
| `items[].bestBeforeOffsetDays` | number | no | The number of days between the expiry date and the best-before date printed on it. |
| `items[].storageTempMin` | decimal | no | The lowest temperature the item can be stored at, in degrees Celsius. |
| `items[].storageTempMax` | decimal | no | The highest temperature the item can be stored at, in degrees Celsius. |
| `items[].createdDate` | date-time | no | The date and time the item was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | date-time | no | The date and time the item record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `pagination` | object | yes | The pagination cursor for this page. Example: `{"hasMore":false}`. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it as page.cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | no | True when more items remain beyond this page. |

```json
{
  "data": {
    "items": [
      {
        "id": "517a93e4-cbb4-4571-9e3d-2343e56cfd84",
        "itemCode": "WIDGET-01",
        "itemName": "Standard widget",
        "itemTypeId": "66aea173-07b8-4c4e-bc4a-5c35dedfdc16",
        "itemTypeName": "Stocked good",
        "categoryId": "6709e2bf-d6cf-4800-9ffa-d5a496ec4d0b",
        "categoryName": "Components",
        "inventoryUnitId": "77bd4c16-e1f0-426d-a98f-07b063df2d9c",
        "inventoryUnitCode": "EA",
        "unitGroupId": "38b5454a-c3fe-452b-9754-61f9ead49e87",
        "unitGroupName": "Each",
        "valuationMethod": "movingAverage",
        "isBatch": false,
        "isSerial": false,
        "isInventory": true,
        "isSalesItem": true,
        "isPurchaseItem": true,
        "active": true,
        "weight": "1.4",
        "weightUnit": "Kg",
        "lastModifiedDate": "2026-08-18T09:14:22.517Z"
      }
    ],
    "pagination": {
      "hasMore": false
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error