# Returns the serial numbers that match the given filters.

`POST /inventory/serial-numbers/search`

Group: Inventory › Serial Numbers · Operation ID: `searchSerialNumbers`

Every criterion is exact and criteria combine with AND. Send an empty filters object to return every serial number.

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

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A serial number must match every filter you send. Send an empty object to return all serial numbers. |
| `filters.serialNumber` | string | no | Limits results to the serial number with this value. The match is exact. |
| `filters.manufacturerSerialNumber` | string | no | Limits results to serial numbers with this manufacturer serial number. The match is exact. |
| `filters.itemId` | string | no | Limits results to serial numbers of this item. An identifier that is not an item's matches no serial number. |
| `filters.locationId` | string | no | Limits results to serial numbers in this warehouse. |
| `filters.active` | boolean | no | Limits results to serial numbers with the given active value. |
| `filters.inStock` | boolean | no | Limits results to serial numbers on hand when true, and to those already gone when false. |
| `filters.isSold` | boolean | no | Limits results to serial numbers with the given isSold value. |
| `filters.expiringBefore` | string (date) | no | Limits results to serial numbers expiring on or before this date. Format YYYY-MM-DD. |
| `filters.expiringAfter` | string (date) | no | Limits results to serial numbers expiring on or after this date. Format YYYY-MM-DD. |
| `filters.modifiedSince` | string (date-time) | no | Limits results to serial numbers 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 serial numbers per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

Example:

```json
{
  "filters": {
    "itemId": "afb4492d-52fc-44c5-ab10-71ad4a615496",
    "inStock": true
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchSerialNumbersOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The serial numbers on this page, oldest first. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the serial number. |
| `items[].serialNumber` | string | no | The serial number assigned to the unit when it was received. It cannot be changed. |
| `items[].manufacturerSerialNumber` | string | no | The manufacturer's own serial number for the unit, where it differs from the assigned serial number. |
| `items[].itemId` | string | no | The unique identifier for the item this unit 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 unit. 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[].entityId` | string | no | The unique identifier for the legal entity the unit belongs to. See id on GET base/entities. |
| `items[].inStock` | string (decimal) | no | 1 while the unit is on hand, 0 once it has gone. |
| `items[].isSold` | boolean | no | Whether the unit has been sold. |
| `items[].cost` | string (decimal) | no | The value the unit is carried at, in the currency named by currency. |
| `items[].originalCost` | string (decimal) | no | The value the unit was carried at when it arrived, in the currency named by currency. |
| `items[].afterSaleCost` | string (decimal) | no | The value of the unit after it was sold, 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[].lastCostChangeDate` | string (date) | no | The date the unit's cost last changed. Format YYYY-MM-DD. |
| `items[].expirationDate` | string (date) | no | The date the unit expires. Format YYYY-MM-DD. |
| `items[].entryDate` | string (date) | no | The date the unit entered the warehouse. Format YYYY-MM-DD. |
| `items[].active` | boolean | no | Whether the serial number can be selected on new documents. |
| `items[].createdDate` | string (date-time) | no | The date and time the serial number record was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | string (date-time) | no | The date and time the serial number 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 serial numbers 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