# Search Inventory Revaluations

`POST /inventory/inventory-revaluations/search`

Group: Inventory › Inventory Revaluations · Operation ID: `searchInventoryRevaluations`

Returns the inventory revaluations that match the given criteria, each with its lines.

Returns the inventory revaluations that match the criteria in the request body, with the same full schema as GET inventory/inventory-revaluations/:id, lines included. This is a query, not a creation: it answers 200 and writes nothing.

itemId and locationId can be searched only here, because both are line fields and the collection endpoint does not carry the lines. An identifier that matches nothing returns an empty page, not an error.

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

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The search criteria, combined with AND. An empty object returns every revaluation, page by page. |
| `filters.documentNumber` | string | no | The exact document number, for example 'REV-1187'. The match is exact, not a substring. |
| `filters.documentStatus` | string | no | Limits results to revaluations with this status. Possible values: 'DRAFT', 'COMMITTED', 'CANCELLED'. The match is exact. |
| `filters.costingValuationType` | string | no | Limits results to revaluations of this kind. Possible values: 'revaluation', 'directCostCapitalisation'. The match is exact. |
| `filters.entityId` | string | no | Limits results to revaluations for this legal entity. See id on GET base/entities. |
| `filters.locationId` | string | no | Limits results to revaluations that have a line for this warehouse. The warehouse is a line field, so the collection endpoint cannot answer this. See id on GET inventory/warehouses/:id. |
| `filters.itemId` | string | no | Limits results to revaluations that have a line for this item. See id on GET inventory/items/:id. |
| `filters.reasonCodeId` | string | no | Limits results to revaluations with this reason code. See id on GET inventory/reason-codes/:id. |
| `filters.fromDate` | string (date) | no | The inclusive lower bound on documentDate. Omit for an open-ended start. Use format YYYY-MM-DD. |
| `filters.toDate` | string (date) | no | The inclusive upper bound on documentDate. Omit for an open-ended end. Use format YYYY-MM-DD. |
| `filters.modifiedSince` | string (date-time) | no | The inclusive lower bound on lastModifiedDate, the incremental-sync filter, distinct from the documentDate window. Use 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 revaluations per page. Defaults to 50. The maximum is 200. |

Example:

```json
{
  "filters": {
    "itemId": "517a93e4-cbb4-4571-9e3d-2343e56cfd84",
    "documentStatus": "COMMITTED"
  },
  "page": {
    "size": 50
  }
}
```

## Response

`200` Success

Under `data` (searchInventoryRevaluationsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The revaluations on this page, oldest first, each with its lines. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the revaluation. |
| `items[].documentNumber` | string | no | The revaluation's document number, for example 'REV-1187'. |
| `items[].documentStatus` | string | yes | The status of the revaluation. Possible values: 'DRAFT', 'COMMITTED', 'CANCELLED'. |
| `items[].documentDate` | string (date) | no | The date the revaluation is dated. Format YYYY-MM-DD. |
| `items[].entityId` | string | no | The unique identifier for the legal entity whose books this moves. See id on GET base/entities. |
| `items[].entityName` | string | no | The display name of that legal entity. |
| `items[].costingValuationType` | string | no | How the value change is recorded. Possible values: 'revaluation', 'directCostCapitalisation'. 'revaluation' restates the cost outright, and 'directCostCapitalisation' adds a cost that was expensed elsewhere onto the stock. |
| `items[].capitalisationExpenseAccountId` | string | no | The unique identifier for the GL account a direct cost capitalization takes the expense off. Absent on an ordinary revaluation. See id on GET accounting/chart-of-accounts/:id. |
| `items[].costingElementTypeId` | string | no | The unique identifier for the costing element type the cost breakdown rows are recorded against. Required to commit. |
| `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 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 revaluation, the legal entity's functional currency. Format ISO 4217, for example 'EUR'. |
| `items[].totalRevaluationAmount` | string (decimal) | no | The sum of every line's revaluationAmount, in the revaluation's currency. This is what the document moves on the balance sheet. |
| `items[].active` | boolean | no | Whether the document is active. |
| `items[].notes` | string | no | Free text on the revaluation. |
| `items[].lineCount` | number | no | How many lines the revaluation has. |
| `items[].createdDate` | string (date-time) | no | The date and time the revaluation was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | string (date-time) | no | The date and time the revaluation record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lines` | array of object | no | The lines of the revaluation. |
| `items[].lines[].id` | string | yes | The unique identifier for the revaluation line. Pass it in updateLines or deleteLines on PATCH inventory/inventory-revaluations/:id to change or remove the line. |
| `items[].lines[].itemId` | string | no | The unique identifier for the item being revalued. See id on GET inventory/items/:id. |
| `items[].lines[].itemCode` | string | no | The code of that item. |
| `items[].lines[].itemName` | string | no | The display name of that item. |
| `items[].lines[].locationId` | string | no | The unique identifier for the warehouse whose stock this line restates. The same item may be carried at a different cost in each warehouse. See id on GET inventory/warehouses/:id. |
| `items[].lines[].locationCode` | string | no | The code of that warehouse. |
| `items[].lines[].locationName` | string | no | The display name of that warehouse. |
| `items[].lines[].unitId` | string | no | The unique identifier for the unit the quantity is in. See id on GET inventory/unit-of-measures/:id. |
| `items[].lines[].unitCode` | string | no | The code of that unit. |
| `items[].lines[].quantity` | string (decimal) | no | How much stock this line restates the cost of, in the line's unit. |
| `items[].lines[].inventoryQuantity` | string (decimal) | no | The same amount in the item's stocking unit. |
| `items[].lines[].currentUnitCost` | string (decimal) | no | What the stock is carried at today, in the revaluation's currency. You supply it and the platform checks it rather than deriving it. Read it from GET inventory/inventory-levels. |
| `items[].lines[].newUnitCost` | string (decimal) | no | What it should be carried at after this posts, in the revaluation's currency. |
| `items[].lines[].previousAfterSaleCost` | string (decimal) | no | The accrued after-sale cost before this document, in the revaluation's currency. Moving-average direct cost capitalization only. |
| `items[].lines[].newAfterSaleCost` | string (decimal) | no | The after-sale cost to capitalize, in the revaluation's currency. Moving-average direct cost capitalization only. |
| `items[].lines[].revaluationAmount` | string (decimal) | no | The value this line moves on the balance sheet, in the revaluation's currency: (newUnitCost - currentUnitCost) x quantity. |
| `items[].lines[].status` | string | no | Where the line sits in the platform's own process. This is free text with no fixed set of values. |
| `items[].lines[].notes` | string | no | Free text on the line. |
| `items[].lines[].batches` | array of object | no | The batches being restated. Their quantities must add up to the line's quantity. |
| `items[].lines[].batches[].batchNumberId` | string | no | The unique identifier for the batch number. |
| `items[].lines[].batches[].batchNumber` | string | no | The batch number itself. |
| `items[].lines[].batches[].quantity` | string (decimal) | no | How much of the line this batch accounts for. |
| `items[].lines[].batches[].currentUnitCost` | string (decimal) | no | What this batch is carried at today, in the revaluation's currency. |
| `items[].lines[].batches[].newUnitCost` | string (decimal) | no | What it should be carried at. |
| `items[].lines[].serials` | array of object | no | The serialized units being restated, one entry per unit, so there must be exactly as many as the quantity says. |
| `items[].lines[].serials[].serialNumberId` | string | no | The unique identifier for the serial number. |
| `items[].lines[].serials[].serialNumber` | string | no | The serial number itself. |
| `items[].lines[].serials[].currentUnitCost` | string (decimal) | no | What this unit is carried at today, in the revaluation's currency. |
| `items[].lines[].serials[].newUnitCost` | string (decimal) | no | What it should be carried at. |
| `items[].lines[].serials[].previousAfterSaleCost` | string (decimal) | no | The unit's accrued after-sale cost before this document. Direct cost capitalization on a sold serial only. |
| `items[].lines[].serials[].newAfterSaleCost` | string (decimal) | no | The after-sale cost to capitalize on it. |
| `pagination` | object | yes | The pagination cursor for this page. |
| `pagination.nextCursor` | string | no | The cursor to pass as page.cursor for the next page. Absent on the last page. |
| `pagination.hasMore` | boolean | yes | Whether more results 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