# Returns the bins that match the given filters.

`POST /inventory/bins/search`

Group: Inventory › Bins · Operation ID: `searchBins`

Every criterion is exact and criteria combine with AND. Send an empty filters object to return every bin. withoutLimits returns only the bins that were given no quantity, weight or volume limit, the ones no capacity check can protect. capacity is not returned here: it is computed per bin and comes back only on GET inventory/bins/:id.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=searchBins)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"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`: searchBinsInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A bin must match every filter you send. Send an empty object to return all bins. |
| `filters.binCode` | string | no | Limits results to the bin with this code. The match is exact. Codes are unique, so this matches at most one bin. |
| `filters.barcode` | string | no | Limits results to the bin with this barcode. The match is exact. Barcodes are unique, so this matches at most one bin. |
| `filters.locationId` | string | no | Limits results to bins in the warehouse with this identifier. An identifier that is not a warehouse matches nothing. See id on GET inventory/warehouses/:id. |
| `filters.aisle` | string | no | Limits results to bins in this aisle. The match is exact. |
| `filters.rack` | string | no | Limits results to bins on this rack. The match is exact. |
| `filters.zone` | string | no | Limits results to bins in this zone. The match is exact. |
| `filters.isPickingBin` | boolean | no | Limits results to picking locations when true, or to bins that are not when false. Omit to match both. |
| `filters.isReceivingBin` | boolean | no | Limits results to bins that stage newly received goods when true, or to bins that do not when false. Omit to match both. |
| `filters.isProductionBin` | boolean | no | Limits results to bins that feed or receive production when true, or to bins that do not when false. Omit to match both. |
| `filters.supportsPerishable` | boolean | no | Limits results to bins that may keep perishable stock when true, or to bins that may not when false. Omit to match both. |
| `filters.capacityCheckMode` | string | no | Limits results to bins with this capacity check mode. Accepted values: 'HardBlock', 'SoftWarning'. |
| `filters.tempZone` | string | no | Limits results to bins in this temperature zone. The match is exact. |
| `filters.active` | boolean | no | Limits results to bins that may be chosen for new movements when true, or to retired ones when false. Omit to match both. |
| `filters.withoutLimits` | boolean | no | True to return only bins that have no quantity, weight or volume limit, the ones no capacity check can protect. |
| `filters.modifiedSince` | string (date-time) | no | Limits results to bins changed on or after this time. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `page` | object | no | The pagination controls. Omit for the first page. |
| `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 bins per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

Example:

```json
{
  "filters": {
    "withoutLimits": true,
    "isPickingBin": true
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchBinsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The bins on this page, oldest first. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the bin. |
| `items[].binCode` | string | no | The short code that identifies the bin, for example 'A-01-1'. It is unique within the tenant, not per warehouse, and cannot be changed after the bin is created. |
| `items[].barcode` | string | no | The barcode printed on the bin label. It is unique within the tenant and cannot be changed after the bin is created. |
| `items[].locationId` | string | no | The unique identifier for the warehouse the bin is in. It cannot be changed after the bin is created. See id on GET inventory/warehouses/:id. |
| `items[].locationCode` | string | no | The code of that warehouse. |
| `items[].locationName` | string | no | The name of that warehouse. |
| `items[].aisle` | string | no | The aisle in the warehouse layout. |
| `items[].rack` | string | no | The rack within the aisle. |
| `items[].shelfLevel` | string | no | The shelf level within the rack. |
| `items[].zone` | string | no | The logical zone of the bin, as your tenant names them. For example 'Picking', 'Storage' or 'Quarantine'. |
| `items[].itemPosition` | string | no | The position within the shelf, where a bin is subdivided further. |
| `items[].isPickingBin` | boolean | no | Whether the bin is a picking location, a fast-access place stock is taken from to fulfill shipments. |
| `items[].isReceivingBin` | boolean | no | Whether the bin stages newly received goods before they are put away. |
| `items[].isProductionBin` | boolean | no | Whether the bin feeds or receives production. |
| `items[].maxQuantity` | number | no | The largest number of units the bin will hold. It is meaningful only when everything in the bin is counted in the same unit. |
| `items[].maxWeight` | string (decimal) | no | The largest weight the bin will hold, in maxWeightUnit. |
| `items[].maxWeightUnit` | string | no | The unit maxWeight is given in. Possible values: 'G', 'Kg', 'Lbs'. |
| `items[].maxVolume` | string (decimal) | no | The largest volume the bin will hold, in maxVolumeUnit. |
| `items[].maxVolumeUnit` | string | no | The unit maxVolume is given in. Possible values: 'L'. |
| `items[].capacityCheckMode` | string | no | What happens when a movement would exceed a limit. Possible values: 'HardBlock', which refuses the movement, and 'SoftWarning', which allows it and flags it. |
| `items[].tempZone` | string | no | The temperature zone the bin belongs to, as your tenant names them. For example 'Ambient', 'Chilled' or 'Frozen'. |
| `items[].tempMin` | string (decimal) | no | The lowest temperature kept in the bin, in degrees Celsius. |
| `items[].tempMax` | string (decimal) | no | The highest temperature kept in the bin, in degrees Celsius. |
| `items[].supportsPerishable` | boolean | no | Whether perishable stock may be kept in the bin. |
| `items[].active` | boolean | no | Whether the bin may be chosen for new movements. When false, the stock already in the bin stays there but no new movement can be assigned to it. |
| `items[].createdDate` | string (date-time) | no | The date and time the bin was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | string (date-time) | no | The date and time the bin record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `pagination` | object | yes | The pagination cursor for this page. |
| `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 bins remain beyond this page. |

## Statuses

- `400` — Invalid request or business failure
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error