# Search warehouse transfers

Operation ID: `searchWarehouseTransfers`

Group: Inventory › Warehouse Transfers

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

`POST /inventory/warehouse-transfers/search`

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

Searches warehouse transfers. Each transfer comes back in full, lines included, with the same fields as GET inventory/warehouse-transfers/:id.

This endpoint can filter by itemId and referenceNumber, which the collection GET inventory/warehouse-transfers can't. itemId matches transfers that have at least one line for the 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`: searchWarehouseTransfersInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A transfer must match every filter you send. Send an empty object to return all transfers. Example: `{"transferType":"INTERCOMPANY","billingStatus":"NOT_BILLED"}`. |
| `filters.documentNumber` | string | no | Limits results to the transfer with this number, for example 'WTR-2291'. The match is exact. |
| `filters.documentStatus` | string | no | Limits results to transfers with this status. Accepted values: 'DRAFT', 'COMMITTED', 'CANCELLED'. |
| `filters.transferType` | string | no | Limits results to transfers of this type. Accepted values: 'NORMAL', 'INTERCOMPANY', 'INTERCOMPANY_RETURN'. |
| `filters.billingStatus` | string | no | Limits results to transfers with this billing status. Accepted values: 'NOT_BILLED', 'BILLED'. |
| `filters.entityId` | string | no | Limits results to transfers whose goods leave this legal entity. See id on GET base/entities. |
| `filters.toEntityId` | string | no | Limits results to transfers whose goods go to this legal entity, on an intercompany transfer. See id on GET base/entities. |
| `filters.locationId` | string | no | Limits results to transfers whose goods leave this warehouse. See id on GET inventory/warehouses/:id. |
| `filters.targetLocationId` | string | no | Limits results to transfers whose goods go to this warehouse. See id on GET inventory/warehouses/:id. |
| `filters.itemId` | string | no | Limits results to transfers with a line for this item. See id on GET inventory/items/:id. |
| `filters.referenceNumber` | string | no | Limits results to transfers with this reference. The match is exact. |
| `filters.fromDate` | date | no | Limits results to transfers dated on or after this date. Use format YYYY-MM-DD. |
| `filters.toDate` | date | no | Limits results to transfers dated on or before this date. Use format YYYY-MM-DD. |
| `filters.modifiedSince` | date-time | no | Limits results to transfers changed on or after this time. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `page` | object | no | The pagination controls. Omit for the first page. Example: `{"size":50}`. |
| `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 transfers per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

```json
{
  "filters": {
    "transferType": "INTERCOMPANY",
    "billingStatus": "NOT_BILLED"
  },
  "page": {
    "size": 50
  }
}
```

## Response

`200` Success

Under `data` (searchWarehouseTransfersOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The transfers on this page, oldest first, each with its lines. An empty array when nothing matches. Example: `[{"id":"9f3e71c5-2a48-4d09-b6e3-8c1d05a4f279","documentNumber":"WTR-2292","documentStatus":"COMMITTED","transferType":"INTERCOMPANY","billingStatus":"NOT_BILLED","lineCount":1,"lastModifiedDate":"2026-08-18T09:14:22.517Z"}]`. |
| `items[].id` | string | yes | The unique identifier for the transfer. |
| `items[].documentNumber` | string | no | The transfer's number, for example 'WTR-2291'. |
| `items[].documentStatus` | string | yes | The status of the transfer. Possible values: 'DRAFT', 'COMMITTED', 'CANCELLED'. |
| `items[].documentDate` | date | no | The date the transfer is dated. Format YYYY-MM-DD. |
| `items[].referenceNumber` | string | no | Your own reference on the transfer. |
| `items[].transferType` | string | no | The type of transfer. Possible values: 'NORMAL', 'INTERCOMPANY', 'INTERCOMPANY_RETURN'. An intercompany transfer sells the goods to another legal entity and can be billed. |
| `items[].entityId` | string | no | The legal entity the goods leave. See id on GET base/entities. |
| `items[].entityName` | string | no | The name of that legal entity. |
| `items[].toEntityId` | string | no | The legal entity receiving the goods, on an intercompany transfer. See id on GET base/entities. |
| `items[].toEntityName` | string | no | The name of that legal entity. |
| `items[].locationId` | string | no | The warehouse the goods leave. See id on GET inventory/warehouses/:id. |
| `items[].locationCode` | string | no | The code of that warehouse. |
| `items[].locationName` | string | no | The name of that warehouse. |
| `items[].targetLocationId` | string | no | The warehouse the goods go to. See id on GET inventory/warehouses/:id. |
| `items[].targetLocationCode` | string | no | The code of that warehouse. |
| `items[].targetLocationName` | string | no | The name of that warehouse. |
| `items[].billingStatus` | string | no | The billing status of the transfer. Possible values: 'NOT_BILLED', 'BILLED'. Only an intercompany transfer is billed, through POST inventory/warehouse-transfers/:id/bill. |
| `items[].intercompanyBillId` | string | no | The numeric id of the intercompany bill this transfer created, not a UUID. It does not match id on GET accounting/intercompany-bills/:id. |
| `items[].contractualCurrency` | string | no | The currency an intercompany transfer is contracted in. Format ISO 4217, for example 'EUR'. Each line's unitTransferValue is stated in it. |
| `items[].currency` | string | no | The currency sourceAmount is stated in, the source entity's functional currency. Format ISO 4217, for example 'EUR'. |
| `items[].sourceAmount` | decimal | no | What the goods were worth leaving the source entity, in currency. Written by the commit. |
| `items[].destinationCurrency` | string | no | The currency destinationAmount is stated in, the destination entity's functional currency. Format ISO 4217, for example 'GBP'. Differs from currency on an intercompany transfer between entities with different functional currencies. |
| `items[].destinationAmount` | decimal | no | What the goods were worth arriving at the destination entity, in destinationCurrency. Written by the commit. On an intercompany transfer it differs from sourceAmount; when both share a currency, the difference is the margin. |
| `items[].notes` | string | no | Free text on the document. |
| `items[].lineCount` | number | no | The number of lines on the transfer. |
| `items[].createdDate` | date-time | no | The date and time the transfer was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | date-time | no | The date and time the transfer record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lines` | array<object> | no | The lines of the transfer. The collection GET inventory/warehouse-transfers returns lineCount in place of these. |
| `items[].lines[].id` | string | yes | The unique identifier for the transfer line. updateLines and deleteLines address lines by it. |
| `items[].lines[].itemId` | string | no | The item being moved. See id on GET inventory/items/:id. |
| `items[].lines[].itemCode` | string | no | The code of that item. |
| `items[].lines[].itemName` | string | no | The name of that item. |
| `items[].lines[].locationId` | string | no | The warehouse this line draws from, the document's warehouse applied to every line. See id on GET inventory/warehouses/:id. |
| `items[].lines[].locationCode` | string | no | The code of that warehouse. |
| `items[].lines[].locationName` | string | no | The name of that warehouse. |
| `items[].lines[].targetLocationId` | string | no | The warehouse this line delivers to. See id on GET inventory/warehouses/:id. |
| `items[].lines[].targetLocationCode` | string | no | The code of that warehouse. |
| `items[].lines[].targetLocationName` | string | no | The name of that warehouse. |
| `items[].lines[].unitId` | string | no | 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` | decimal | no | How much moves, in the line's unit. |
| `items[].lines[].inventoryQuantity` | decimal | no | The same amount in the item's stocking unit, which is what the warehouse counts. |
| `items[].lines[].transferCost` | decimal | no | What one unit left the source warehouse at, in the transfer's currency. The valuation method sets it at commit. Absent on a draft. |
| `items[].lines[].unitTransferValue` | decimal | no | The contractual price of one unit on an intercompany transfer, in the contractual currency. Supplied on create. |
| `items[].lines[].totalTransferValue` | decimal | no | The line's total on an intercompany transfer, in the contractual currency: totalTransferValue = unitTransferValue x quantity. Written by the platform. |
| `items[].lines[].returnedQuantity` | decimal | no | How much of this line has come back on an intercompany return. |
| `items[].lines[].status` | string | no | The status of the line. |
| `items[].lines[].notes` | string | no | Free text on the line. |
| `items[].lines[].batches` | array<object> | no | The batches that make up the line's quantity. |
| `items[].lines[].batches[].batchNumberId` | string | no | The unique identifier for the batch number. See id on GET inventory/batch-numbers/:id. |
| `items[].lines[].batches[].batchNumber` | string | no | The batch number. |
| `items[].lines[].batches[].quantity` | decimal | no | How much of the line this batch accounts for. |
| `items[].lines[].batches[].inventoryQuantity` | decimal | no | The same amount in the item's stocking unit. |
| `items[].lines[].batches[].unitCost` | decimal | no | What this batch moved at, in the transfer's currency. Set at commit. |
| `items[].lines[].serials` | array<object> | no | The serialized units that move. |
| `items[].lines[].serials[].serialNumberId` | string | no | The unique identifier for the serial number. See id on GET inventory/serial-numbers/:id. |
| `items[].lines[].serials[].serialNumber` | string | no | The serial number. |
| `items[].lines[].serials[].quantity` | decimal | no | Always one, for a serialized unit. |
| `items[].lines[].serials[].unitCost` | decimal | no | What this unit moved at, in the transfer's currency. Set at commit. |
| `items[].lines[].binLocations` | array<object> | no | The bins the goods leave and arrive in. Each entry names both ends of the move, and the batch or serial it belongs to where it belongs to one. |
| `items[].lines[].binLocations[].fromBinLocationId` | string | no | The bin the goods leave, in the source warehouse. See id on GET inventory/bins/:id. |
| `items[].lines[].binLocations[].fromBinLocationCode` | string | no | The code of that bin. |
| `items[].lines[].binLocations[].toBinLocationId` | string | no | The bin the goods arrive in, in the target warehouse. See id on GET inventory/bins/:id. |
| `items[].lines[].binLocations[].toBinLocationCode` | string | no | The code of that bin. |
| `items[].lines[].binLocations[].quantity` | decimal | no | How much moves between these two bins. |
| `items[].lines[].binLocations[].inventoryQuantity` | decimal | no | The same amount in the item's stocking unit. |
| `items[].lines[].binLocations[].batchNumber` | string | no | The batch this entry belongs to, when it belongs to one of the line's batches. |
| `items[].lines[].binLocations[].serialNumber` | string | no | The serialized unit this entry belongs to, when it belongs to one of the line's serials. |
| `pagination` | object | yes | The pagination cursor 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 | True when more transfers remain beyond this page. |

```json
{
  "data": {
    "items": [
      {
        "id": "9f3e71c5-2a48-4d09-b6e3-8c1d05a4f279",
        "documentNumber": "WTR-2292",
        "documentStatus": "COMMITTED",
        "transferType": "INTERCOMPANY",
        "billingStatus": "NOT_BILLED",
        "lineCount": 1,
        "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