# Search serial numbers

Operation ID: `searchSerialNumbers`

Group: Inventory › Serial Numbers

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

`POST /inventory/serial-numbers/search`

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

Searches serial numbers, with their costs.

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A unit must match every filter you send. Send an empty object to return all units. Example: `{"itemId":"afb4492d-52fc-44c5-ab10-71ad4a615496","inStock":true}`. |
| `filters.serialNumber` | string | no | Limits results to units with this serial number. The match is exact. |
| `filters.manufacturerSerialNumber` | string | no | Limits results to units with this manufacturer's serial number. The match is exact. |
| `filters.itemId` | string | no | Limits results to units for the item with this unique identifier. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `filters.locationId` | string | no | Limits results to units in the warehouse with this unique identifier. Units that were shipped or removed from the warehouse are included. Format: UUID. See `id` on GET inventory/warehouses/:id (getWarehouse). |
| `filters.active` | boolean | no | Limits results to active units when true, and to inactive units when false. |
| `filters.inStock` | boolean | no | Limits results to units in stock when true, and to units not in stock when false. |
| `filters.isSold` | boolean | no | Limits results to units that have been sold when true, and to units that have not been sold when false. A unit that was sold and then returned counts as not sold. |
| `filters.expiringBefore` | date | no | Limits results to units expiring on or before this date. Format: YYYY-MM-DD. |
| `filters.expiringAfter` | date | no | Limits results to units expiring on or after this date. Format: YYYY-MM-DD. |
| `filters.modifiedSince` | date-time | no | Limits results to units changed on or after this time. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| `page` | object | no | The page to return and its size. Omit to get the first page at the default size. |
| `page.cursor` | string | no | The cursor from the previous response's `pagination.nextCursor`. Send it exactly as you received it. Omit on the first request. |
| `page.size` | number | no | The number of units per page, from 1 to 200. Defaults to 50. A value above 200 is treated as 200, not rejected. |

```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<object> | yes | The matching units in this response. When more units match than fit in one response, use `pagination` to get the rest. Empty when nothing matches. Example: `[{"id":"c3f80a41-6d29-4b57-8e10-92a4d7b05f63","serialNumber":"SN-000418","manufacturerSerialNumber":"MFG-77-000418","itemId":"afb4492d-52fc-44c5-ab10-71ad4a615496","itemCode":"SERIAL-01","locationId":"f5272ae0-0f0b-47d2-b78a-2158fec2cc32","locationCode":"WH-02","inStock":"1","isSold":false,"cost":"250","originalCost":"250","currency":"GBP","active":true,"lastModifiedDate":"2026-08-18T09:14:22.517Z"}]`. |
| `items[].id` | string | yes | The unique identifier for the serial number. Format: UUID. |
| `items[].serialNumber` | string | no | The serial number of the unit, such as the one printed on its label. It is entered on the receipt, inventory increase, or other document that first recorded the unit. The same serial number can be used for other items and in other legal entities, so it identifies a unit only together with the item and the legal entity. |
| `items[].manufacturerSerialNumber` | string | no | The manufacturer's serial number. |
| `items[].itemId` | string | no | The unique identifier of the item this serial number belongs to. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `items[].itemCode` | string | no | The code of the item in `itemId`. |
| `items[].itemName` | string | no | The name of the item in `itemId`. |
| `items[].locationId` | string | no | The unique identifier of the warehouse the unit is in, or was last in. Format: UUID. See `id` on GET inventory/warehouses/:id (getWarehouse). |
| `items[].locationCode` | string | no | The code of the warehouse in `locationId`. |
| `items[].locationName` | string | no | The name of the warehouse in `locationId`. |
| `items[].entityId` | string | no | The unique identifier of the legal entity the unit belongs to. Format: UUID. See `id` on GET base/entities (entities). |
| `items[].inStock` | decimal | no | The current quantity of the unit in stock. It is 1 when the unit is in stock and 0 when it is not, including before the unit is received. |
| `items[].isSold` | boolean | no | Whether the unit has been sold. |
| `items[].cost` | decimal | no | The cost of the unit. Cost changes made after the unit is sold are in `afterSaleCost`. |
| `items[].originalCost` | decimal | no | The cost of the unit when it was first received. While the unit is in stock, landed costs added later, such as freight or customs duty, raise it, and other revaluations can raise or lower it. When the unit is received again on a receipt or inventory increase after it left stock, it is reset to the cost on that document. A sales return or a canceled shipment does not reset it. |
| `items[].afterSaleCost` | decimal | no | The total of the cost changes made to the unit after it was sold, such as a landed cost added later. Absent when the unit has had no cost changes since it was sold. |
| `items[].currency` | string | no | The currency of `cost`, `originalCost`, and `afterSaleCost`. Format: ISO 4217, for example 'USD'. |
| `items[].lastCostChangeDate` | date | no | The date the `cost` or `afterSaleCost` of the unit last changed. It is the date the change was committed, not the date of the document. Format: YYYY-MM-DD. |
| `items[].expirationDate` | date | no | The date the unit expires. Format: YYYY-MM-DD. |
| `items[].entryDate` | date | no | The date the unit's age is counted from. Format: YYYY-MM-DD. When a receipt or inventory increase receives the unit, it is the date entered for the unit on that document, or the document's date when none was entered. Each later receipt or inventory increase for the unit sets a new date. A warehouse transfer does not change the date, including a transfer between legal entities. |
| `items[].active` | boolean | no | Whether the serial number is active. |
| `items[].createdDate` | date-time | no | The date and time the serial number record was created, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | 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 | Whether there are more results than are in this response, and the cursor you use to get the next ones. Example: `{"hasMore":false}`. |
| `pagination.nextCursor` | string | no | The cursor that marks where this response stopped. To get the next results, send it as `page.cursor` in your next request. Absent when there are no more results. |
| `pagination.hasMore` | boolean | no | Whether there are more results than are in this response. |

```json
{
  "data": {
    "items": [
      {
        "id": "c3f80a41-6d29-4b57-8e10-92a4d7b05f63",
        "serialNumber": "SN-000418",
        "manufacturerSerialNumber": "MFG-77-000418",
        "itemId": "afb4492d-52fc-44c5-ab10-71ad4a615496",
        "itemCode": "SERIAL-01",
        "locationId": "f5272ae0-0f0b-47d2-b78a-2158fec2cc32",
        "locationCode": "WH-02",
        "inStock": "1",
        "isSold": false,
        "cost": "250",
        "originalCost": "250",
        "currency": "GBP",
        "active": true,
        "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