# Search inventory increases

Operation ID: `searchInventoryIncreases`

Group: Inventory › Inventory Increases

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

`POST /inventory/inventory-increases/search`

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

Searches inventory increases. Each matching inventory increase comes back with its main fields, its lines, and each line's batch, serial, and bin details. The fields are the same as on GET inventory/inventory-increases/:id.

This is the only endpoint that filters by item. itemId matches inventory increases that have a line for that item.

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The search criteria. An inventory increase must match every criterion you send. Omit to return every inventory increase. Example: `{"documentStatus":"DRAFT","locationId":"e1d84c07-5b39-4a26-9f70-2c8b613ad495"}`. |
| `filters.documentNumber` | string | no | Limits results to the inventory increase with this document number, for example 'INC-42'. The match is exact. |
| `filters.documentStatus` | string | no | Limits results to inventory increases with this status. Accepted values: 'DRAFT', 'COMMITTED', 'CANCELLED'. Any other value matches no inventory increase. |
| `filters.entityId` | string | no | Limits results to inventory increases for this legal entity. See id on GET base/entities. |
| `filters.locationId` | string | no | Limits results to inventory increases at this warehouse. See id on GET inventory/warehouses/:id. |
| `filters.reasonCodeId` | string | no | Limits results to inventory increases with this reason code. See id on GET inventory/reason-codes/:id. |
| `filters.itemId` | string | no | Limits results to inventory increases that have a line for this item. See id on GET inventory/items/:id. |
| `filters.fromDate` | date | no | Limits results to inventory increases dated on or after this date. Omit for an open-ended start. Format YYYY-MM-DD. |
| `filters.toDate` | date | no | Limits results to inventory increases dated on or before this date. Omit for an open-ended end. Format YYYY-MM-DD. |
| `filters.modifiedSince` | date-time | no | Limits results to inventory increases changed on or after this time, in UTC. 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 on the first request. |
| `page.size` | number | no | The number of inventory increases per page, between 1 and 200. Defaults to 50. A value above 200 is treated as 200. |

```json
{
  "filters": {
    "documentStatus": "DRAFT",
    "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495"
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchInventoryIncreasesOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The inventory increases on this page, oldest first, each with its lines. An empty array when nothing matches. Example: `[{"id":"d4a17f28-6b93-4c50-8e71-2a5d0c9b3e64","documentNumber":"INC-42","documentStatus":"DRAFT","documentDate":"2026-08-14","entityId":"1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43","entityName":"Acme Netherlands B.V.","locationId":"e1d84c07-5b39-4a26-9f70-2c8b613ad495","locationCode":"WH-01","locationName":"Rotterdam Distribution Centre","reasonCodeId":"6f2b58c1-9d47-4e03-a815-70c9d2e46b38","reasonCode":"COUNT","reasonCodeDescription":"Count correction","currency":"EUR","notes":"August cycle count","createdDate":"2026-08-14T09:12:00.000Z","lastModifiedDate":"2026-08-14T09:12:00.000Z","lines":[{"id":"9b3f5a10-7c24-4e68-8d05-1f6a92b4c837","itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","itemCode":"WIDGET-01","itemName":"Standard widget","unitId":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","unitCode":"EA","quantity":"120.00","inventoryQuantity":"120.00","unitPrice":"3.75","notes":"Found during the August count","batches":[{"batchNumberId":"9c31f5a8-6b02-4e79-b354-8d1a67e0f2b9","batchNumber":"LOT-2026-08-14","expirationDate":"2027-08-14","quantity":"120.00","inventoryQuantity":"120.00","unitCost":"3.75"}],"binLocations":[{"binLocationId":"0c7e91d3-4a58-4b26-9e10-63f8a2c5d704","binLocationCode":"A-01-02","quantity":"120.00","inventoryQuantity":"120.00","batchNumber":"LOT-2026-08-14"}]}]}]`. |
| `items[].id` | string | yes | The unique identifier for the inventory increase. |
| `items[].documentNumber` | string | no | The inventory increase's document number, for example 'INC-42'. Absent while none has been assigned. |
| `items[].documentStatus` | string | yes | The status of the inventory increase. Possible values: 'DRAFT', 'COMMITTED', 'CANCELLED'. |
| `items[].documentDate` | date | yes | The date the inventory increase is dated. It sets the posting period. Format YYYY-MM-DD. |
| `items[].entityId` | string | yes | The unique identifier for the legal entity the inventory increase belongs to. See id on GET base/entities. |
| `items[].entityName` | string | no | The display name of that legal entity. |
| `items[].locationId` | string | no | The unique identifier for the warehouse the stock is added to. One warehouse for the whole inventory increase. Absent only on a document with no lines. See id on GET inventory/warehouses/:id. |
| `items[].locationCode` | string | no | The short code of that warehouse. |
| `items[].locationName` | string | no | The display name of that warehouse. |
| `items[].reasonCodeId` | string | no | The unique identifier for the reason code, when one was given. See id on GET inventory/reason-codes/:id. |
| `items[].reasonCode` | string | no | The short code of that reason code. |
| `items[].reasonCodeDescription` | string | no | The description of that reason code. |
| `items[].currency` | string | no | The currency of every amount on the inventory increase. Format ISO 4217, for example 'EUR'. |
| `items[].notes` | string | no | Free text on the inventory increase. |
| `items[].createdDate` | date-time | no | The date and time the inventory increase was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | date-time | no | The date and time the inventory increase record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lines` | array<object> | yes | The lines of the inventory increase. An inventory increase always has at least one. |
| `items[].lines[].id` | string | yes | The unique identifier for the inventory increase line. |
| `items[].lines[].itemId` | string | yes | The unique identifier for the item this line adds to stock. See id on GET inventory/items/:id. |
| `items[].lines[].itemCode` | string | no | The short code of that item. |
| `items[].lines[].itemName` | string | no | The display name of that item. |
| `items[].lines[].unitId` | string | yes | The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id. |
| `items[].lines[].unitCode` | string | no | The short code of that unit, for example 'BOX'. |
| `items[].lines[].quantity` | decimal | yes | The quantity added, in the line's unit. |
| `items[].lines[].inventoryQuantity` | decimal | no | The same quantity in the item's stocking unit. |
| `items[].lines[].unitPrice` | decimal | no | The value of one unit, in the inventory increase's currency. |
| `items[].lines[].lineValue` | decimal | no | The total value of the line, in the inventory increase's currency, when the line was valued as a whole rather than per unit. When present it is what the line is worth, and unitPrice is calculated from it as lineValue divided by quantity. Absent on a line valued by unitPrice. |
| `items[].lines[].notes` | string | no | Free text on the line. |
| `items[].lines[].batches` | array<object> | no | The batches making up this line's quantity, for a batch-tracked item. Absent when the item is not batch-tracked. |
| `items[].lines[].batches[].batchNumberId` | string | no | The unique identifier for the batch record this entry created or matched. |
| `items[].lines[].batches[].batchNumber` | string | yes | The batch number as printed, for example 'LOT-2026-08-14'. |
| `items[].lines[].batches[].manufacturerBatchNumber` | string | no | The maker's own number for the same batch, when one was recorded. |
| `items[].lines[].batches[].expirationDate` | date | no | The expiration date of the batch. Format YYYY-MM-DD. |
| `items[].lines[].batches[].quantity` | decimal | yes | The quantity of this batch on the line, in the line's unit. |
| `items[].lines[].batches[].inventoryQuantity` | decimal | no | The same quantity in the item's stocking unit. |
| `items[].lines[].batches[].unitCost` | decimal | no | The cost of one unit of this batch, in the inventory increase's currency. |
| `items[].lines[].serials` | array<object> | no | The serialized units making up this line's quantity, one entry per unit. Absent when the item is not serialized. |
| `items[].lines[].serials[].serialNumberId` | string | no | The unique identifier for the serial record this entry created or matched. |
| `items[].lines[].serials[].serialNumber` | string | yes | The serial number stamped on the unit. |
| `items[].lines[].serials[].manufacturerSerialNumber` | string | no | The maker's own number for the same unit, when one was recorded. |
| `items[].lines[].serials[].unitCost` | decimal | no | The cost of this unit, in the inventory increase's currency. |
| `items[].lines[].binLocations` | array<object> | no | The bins the quantity lands in, in a bin-tracked warehouse. Each entry that names a batchNumber or serialNumber belongs to that batch or unit, and one that names neither belongs to the line. |
| `items[].lines[].binLocations[].binLocationId` | string | yes | The unique identifier for the bin the quantity landed in. See id on GET inventory/bins/:id. |
| `items[].lines[].binLocations[].binLocationCode` | string | no | The short code of that bin. |
| `items[].lines[].binLocations[].quantity` | decimal | yes | The quantity landing in this bin, in the line's unit. |
| `items[].lines[].binLocations[].inventoryQuantity` | decimal | no | The same quantity in the item's stocking unit. |
| `items[].lines[].binLocations[].batchNumber` | string | no | The batch this bin entry belongs to, when it belongs to one of the line's batches. |
| `items[].lines[].binLocations[].serialNumber` | string | no | The serialized unit this bin entry belongs to, when it belongs to one of the line's units. |
| `pagination` | object | yes | The pagination for this page. Example: `{"hasMore":false}`. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it as page.cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | yes | Whether more results remain beyond this page. |

```json
{
  "data": {
    "items": [
      {
        "id": "d4a17f28-6b93-4c50-8e71-2a5d0c9b3e64",
        "documentNumber": "INC-42",
        "documentStatus": "DRAFT",
        "documentDate": "2026-08-14",
        "entityId": "1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43",
        "entityName": "Acme Netherlands B.V.",
        "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
        "locationCode": "WH-01",
        "locationName": "Rotterdam Distribution Centre",
        "reasonCodeId": "6f2b58c1-9d47-4e03-a815-70c9d2e46b38",
        "reasonCode": "COUNT",
        "reasonCodeDescription": "Count correction",
        "currency": "EUR",
        "notes": "August cycle count",
        "createdDate": "2026-08-14T09:12:00.000Z",
        "lastModifiedDate": "2026-08-14T09:12:00.000Z",
        "lines": [
          {
            "id": "9b3f5a10-7c24-4e68-8d05-1f6a92b4c837",
            "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
            "itemCode": "WIDGET-01",
            "itemName": "Standard widget",
            "unitId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
            "unitCode": "EA",
            "quantity": "120.00",
            "inventoryQuantity": "120.00",
            "unitPrice": "3.75",
            "notes": "Found during the August count",
            "batches": [
              {
                "batchNumberId": "9c31f5a8-6b02-4e79-b354-8d1a67e0f2b9",
                "batchNumber": "LOT-2026-08-14",
                "expirationDate": "2027-08-14",
                "quantity": "120.00",
                "inventoryQuantity": "120.00",
                "unitCost": "3.75"
              }
            ],
            "binLocations": [
              {
                "binLocationId": "0c7e91d3-4a58-4b26-9e10-63f8a2c5d704",
                "binLocationCode": "A-01-02",
                "quantity": "120.00",
                "inventoryQuantity": "120.00",
                "batchNumber": "LOT-2026-08-14"
              }
            ]
          }
        ]
      }
    ],
    "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