# Returns the batches that match the given filters.

`POST /inventory/batch-numbers/search`

Group: Inventory › Batch Numbers · Operation ID: `searchBatchNumbers`

Every criterion is exact and criteria combine with AND. Send an empty filters object to return every batch. Use expiringBefore for a shelf-life sweep of everything due to expire by a date, which you can narrow to one item or warehouse and combine with inStock for what is still on hand.

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

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A batch must match every filter you send. Send an empty object to return all batches. |
| `filters.batchNumber` | string | no | Limits results to the batch with this batch number. The match is exact. |
| `filters.manufacturerBatchNumber` | string | no | Limits results to batches with this manufacturer batch reference. The match is exact. |
| `filters.itemId` | string | no | Limits results to batches of this item. An identifier that is not an item's matches no batch. |
| `filters.locationId` | string | no | Limits results to batches in this warehouse. |
| `filters.batchStatus` | string | no | Limits results to batches with this status. Accepted values: 'ACTIVE', 'QUARANTINED', 'EXPIRED', 'DISPOSED'. |
| `filters.temperatureBreach` | boolean | no | Limits results to batches with the given temperatureBreach value. |
| `filters.qcStatus` | string | no | Limits results to batches with this quality-control state. The match is exact. |
| `filters.active` | boolean | no | Limits results to batches with the given active value. |
| `filters.inStock` | boolean | no | Limits results to batches with stock left when true, and to exhausted batches when false. |
| `filters.expiringBefore` | string (date) | no | Limits results to batches expiring on or before this date. Format YYYY-MM-DD. |
| `filters.expiringAfter` | string (date) | no | Limits results to batches expiring on or after this date. Format YYYY-MM-DD. |
| `filters.modifiedSince` | string (date-time) | no | Limits results to batches 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 batches per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

Example:

```json
{
  "filters": {
    "expiringBefore": "2026-12-31",
    "inStock": true
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchBatchNumbersOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The batches on this page, oldest first. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the batch. |
| `items[].batchNumber` | string | no | The batch number assigned when the stock was received. It cannot be changed. |
| `items[].manufacturerBatchNumber` | string | no | The manufacturer's own batch reference for this batch, where it differs from the assigned batch number. |
| `items[].itemId` | string | no | The unique identifier for the item this batch is of. See id on GET inventory/items/:id. |
| `items[].itemCode` | string | no | The code of that item. |
| `items[].itemName` | string | no | The display name of that item. |
| `items[].locationId` | string | no | The unique identifier for the warehouse holding the batch. See id on GET inventory/warehouses/:id. |
| `items[].locationCode` | string | no | The code of that warehouse. |
| `items[].locationName` | string | no | The display name of that warehouse. |
| `items[].quantity` | string (decimal) | no | The quantity that arrived in the batch. |
| `items[].inStock` | string (decimal) | no | The quantity still on hand. A status of 'QUARANTINED' or 'EXPIRED' does not reduce it. |
| `items[].cost` | string (decimal) | no | The value the batch is carried at per unit, in the currency named by currency. |
| `items[].originalCost` | string (decimal) | no | The value the batch was carried at per unit when it arrived, in the currency named by currency. |
| `items[].currency` | string | no | The currency the cost fields are stated in. Format ISO 4217, for example 'USD'. |
| `items[].expirationDate` | string (date) | no | The date the batch expires. Format YYYY-MM-DD. |
| `items[].manufactureDate` | string (date) | no | The date the batch was made. Format YYYY-MM-DD. |
| `items[].bestBeforeDate` | string (date) | no | The best-before date printed on the batch, which may differ from the expiry. Format YYYY-MM-DD. |
| `items[].entryDate` | string (date) | no | The date the batch entered the warehouse. Format YYYY-MM-DD. |
| `items[].batchStatus` | string | no | The status of the batch. Possible values: 'ACTIVE', 'QUARANTINED', 'EXPIRED', 'DISPOSED'. Only 'ACTIVE' stock can be picked, and none of the other three values reduces the quantity on hand. |
| `items[].temperatureBreach` | boolean | no | Whether the batch has been outside its storage temperature range. |
| `items[].qcStatus` | string | no | The tenant's own quality-control state for the batch. This is free text. |
| `items[].active` | boolean | no | Whether the batch can be selected on new documents. |
| `items[].createdDate` | string (date-time) | no | The date and time the batch record was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | string (date-time) | no | The date and time the batch 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 batches 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