# Search serial transactions

Operation ID: `searchSerialTransactions`

Group: Inventory › Serial Transactions

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

`POST /inventory/serial-transactions/search`

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

Searches serial transactions. Results are in the order the serial transactions were created, not in order of `transactionDate`.

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A serial transaction must match every filter you send. Send an empty object to return all serial transactions. Example: `{"serialNumber":"SN-000412"}`. |
| `filters.serialNumberId` | string | no | Limits results to serial transactions for the serialized unit with this unique identifier. Format: UUID. See `id` on GET inventory/serial-numbers/:id (getSerialNumber). |
| `filters.serialNumber` | string | no | Limits results to serial transactions for units with this serial number. The match is exact. Example: 'SN-000412'. |
| `filters.manufacturerSerialNumber` | string | no | Limits results to serial transactions for units with this manufacturer's serial number. The match is exact. |
| `filters.isSold` | boolean | no | Limits results to serial transactions for units that have been sold when true, and for units that have not been sold when false. It uses the unit's current value, not the value at the time of the serial transaction. A unit that was sold and then returned counts as not sold. |
| `filters.itemId` | string | no | Limits results to serial transactions for the item with this unique identifier. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `filters.locationId` | string | no | Limits results to serial transactions for the warehouse with this unique identifier. Format: UUID. See `id` on GET inventory/warehouses/:id (getWarehouse). |
| `filters.fromDate` | date | no | Limits results to serial transactions with a `transactionDate` on or after this date. Format: YYYY-MM-DD. |
| `filters.toDate` | date | no | Limits results to serial transactions with a `transactionDate` on or before this date. Format: YYYY-MM-DD. |
| `filters.modifiedSince` | date-time | no | Limits results to serial transactions whose `lastModifiedDate` is 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 serial transactions per page, from 1 to 200. Defaults to 50. A value above 200 is treated as 200, not rejected. |

```json
{
  "filters": {
    "serialNumber": "SN-000412"
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchSerialTransactionsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The matching serial transactions in this response. When more serial transactions match than fit in one response, use `pagination` to get the rest. Empty when nothing matches. Example: `[{"id":"b41e7c05-2d68-4f13-9a70-5c8e1b3d0f92","serialNumberId":"7e05c3a9-64b1-4d82-b0f7-19a4c8e2b537","serialNumber":"SN-000412","manufacturerSerialNumber":"ACME-77-000412","expirationDate":"2029-05-31","entryDate":"2026-08-03","isSold":true,"transactionId":"3a7c1f95-04eb-4d62-8917-5c0e2b8d4a63","itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","itemCode":"LAPTOP-14","itemName":"14-inch laptop","locationId":"e1d84c07-5b39-4a26-9f70-2c8b613ad495","locationCode":"WH-01","locationName":"Rotterdam Distribution Centre","transactionDate":"2026-08-03","inQuantity":"1.00","cost":"742.50","currency":"EUR","sourceDocumentLineType":"InvPurchaseDeliveryLine","lastModifiedDate":"2026-08-03T11:15:00.000Z"},{"id":"c9a2f610-8b34-4e07-a5d1-2f6b93e4c018","serialNumberId":"7e05c3a9-64b1-4d82-b0f7-19a4c8e2b537","serialNumber":"SN-000412","manufacturerSerialNumber":"ACME-77-000412","expirationDate":"2029-05-31","entryDate":"2026-08-03","isSold":true,"transactionId":"8d17b4e2-3c95-4a60-b7f8-01e5d9c26a43","itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","itemCode":"LAPTOP-14","itemName":"14-inch laptop","locationId":"e1d84c07-5b39-4a26-9f70-2c8b613ad495","locationCode":"WH-01","locationName":"Rotterdam Distribution Centre","transactionDate":"2026-08-11","outQuantity":"1.00","cost":"742.50","currency":"EUR","sourceDocumentLineType":"IMInventorySalesDeliveryLine","lastModifiedDate":"2026-08-11T09:02:00.000Z"}]`. |
| `items[].id` | string | yes | The unique identifier for the serial transaction. Format: UUID. |
| `items[].serialNumberId` | string | yes | The unique identifier of the serialized unit this transaction is for. Format: UUID. See `id` on GET inventory/serial-numbers/:id (getSerialNumber). |
| `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. Example: 'SN-000412'. |
| `items[].manufacturerSerialNumber` | string | no | The manufacturer's serial number. It shows the unit's current value, not the value at the time of the serial transaction. |
| `items[].expirationDate` | date | no | The date the unit expires. It shows the unit's current value, not the value at the time of the serial transaction. Format: YYYY-MM-DD. |
| `items[].entryDate` | date | no | The date the unit's age is counted from. Format: YYYY-MM-DD. It is the unit's current `entryDate`, not the date at the time of this serial transaction. |
| `items[].isSold` | boolean | no | Whether the unit has been sold. It shows the unit's current value, not the value at the time of the serial transaction. A unit that was sold and then returned has the value false. |
| `items[].transactionId` | string | no | The unique identifier of the inventory transaction this serial transaction belongs to. Format: UUID. See `id` on GET inventory/inventory-transactions/:id (getInventoryTransaction). |
| `items[].itemId` | string | no | The unique identifier of the item. 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. 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[].transactionDate` | date | no | The date of the inventory transaction this serial transaction belongs to. Format: YYYY-MM-DD. |
| `items[].inQuantity` | decimal | no | The quantity of the unit that came into stock. It is 1 when the unit came in, and 0 when only the unit's cost changed. Absent when the unit went out. |
| `items[].outQuantity` | decimal | no | The quantity of the unit that went out of stock. It is 1 when the unit went out. Absent when the unit came in or only its cost changed. |
| `items[].cost` | decimal | no | The cost of the unit, in the currency named by `currency`. When the unit comes in, it is the cost the unit was received at. When the unit goes out, it is the unit's cost at that time. On an inventory revaluation, it is the unit's new cost. |
| `items[].currency` | string | no | The currency that `cost` is in. Format: ISO 4217, for example 'USD'. |
| `items[].sourceDocumentLineType` | any | no | The type of document line the inventory transaction came from. One of: `"IMInventorySalesOrderLine"`, `"IMInventorySalesDeliveryLine"`, `"IMSalesOrderLine"`, `"IMInventoryPurchaseReturnLine"`, `"IMInventorySalesReturnLine"`, `"IMWarehouseTransferLine"`, `"IMInventoryDecreaseLine"`, `"IMInventoryIncreaseLine"`, `"IMInventoryRevaluationLine"`, `"IMInventoryTransferLine"`, `"IMInventoryAdjustmentLine"`, `"IMInventoryCountLine"`, `"IMInventoryPutAwayTask"`, `"IMInventoryPurchaseReturnReversal"`, `"PurchaseOrderLine"`, `"IMLandedCostAllocationLine"`, `"SalesOrderProductItem"`, `"IMWarehouseTransferOrderLine"`, `"VendorBillItemBase"`, `"InvPurchaseDeliveryLine"`. |
| `items[].lastModifiedDate` | date-time | no | The date and time the serial transaction last changed, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. Changes to the unit itself, such as its `isSold` or `entryDate`, do not update this field. |
| `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 | yes | Whether there are more results than are in this response. |

```json
{
  "data": {
    "items": [
      {
        "id": "b41e7c05-2d68-4f13-9a70-5c8e1b3d0f92",
        "serialNumberId": "7e05c3a9-64b1-4d82-b0f7-19a4c8e2b537",
        "serialNumber": "SN-000412",
        "manufacturerSerialNumber": "ACME-77-000412",
        "expirationDate": "2029-05-31",
        "entryDate": "2026-08-03",
        "isSold": true,
        "transactionId": "3a7c1f95-04eb-4d62-8917-5c0e2b8d4a63",
        "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
        "itemCode": "LAPTOP-14",
        "itemName": "14-inch laptop",
        "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
        "locationCode": "WH-01",
        "locationName": "Rotterdam Distribution Centre",
        "transactionDate": "2026-08-03",
        "inQuantity": "1.00",
        "cost": "742.50",
        "currency": "EUR",
        "sourceDocumentLineType": "InvPurchaseDeliveryLine",
        "lastModifiedDate": "2026-08-03T11:15:00.000Z"
      },
      {
        "id": "c9a2f610-8b34-4e07-a5d1-2f6b93e4c018",
        "serialNumberId": "7e05c3a9-64b1-4d82-b0f7-19a4c8e2b537",
        "serialNumber": "SN-000412",
        "manufacturerSerialNumber": "ACME-77-000412",
        "expirationDate": "2029-05-31",
        "entryDate": "2026-08-03",
        "isSold": true,
        "transactionId": "8d17b4e2-3c95-4a60-b7f8-01e5d9c26a43",
        "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
        "itemCode": "LAPTOP-14",
        "itemName": "14-inch laptop",
        "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
        "locationCode": "WH-01",
        "locationName": "Rotterdam Distribution Centre",
        "transactionDate": "2026-08-11",
        "outQuantity": "1.00",
        "cost": "742.50",
        "currency": "EUR",
        "sourceDocumentLineType": "IMInventorySalesDeliveryLine",
        "lastModifiedDate": "2026-08-11T09:02:00.000Z"
      }
    ],
    "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