# Search warehouse transfer orders

Operation ID: `searchTransferOrders`

Group: Inventory › Warehouse Transfer Orders

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

`POST /inventory/warehouse-transfer-orders/search`

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

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

This endpoint can filter by itemId and referenceNumber, which the collection GET inventory/warehouse-transfer-orders can't. itemId matches orders 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`: searchTransferOrdersInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A transfer order must match every filter you send. Omit to return all transfer orders. Example: `{"documentStatus":"DRAFT","targetLocationId":"e94a17c3-5b28-4d60-91f7-3a8c2e05b6d1"}`. |
| `filters.documentNumber` | string | no | Limits results to the transfer order with this document number, for example 'WTO-1043'. The match is exact. |
| `filters.documentStatus` | string | no | Limits results to transfer orders in this status. Accepted values: 'DRAFT', 'IN_TRANSFER', 'PARTIALLY_PROCESSED', 'PROCESSED'. Any other value matches no transfer order. |
| `filters.entityId` | string | no | Limits results to transfer orders for this legal entity. See id on GET base/entities. |
| `filters.locationId` | string | no | Limits results to transfer orders with this source warehouse on the header. See id on GET inventory/warehouses/:id. |
| `filters.targetLocationId` | string | no | Limits results to transfer orders with this target warehouse on the header. See id on GET inventory/warehouses/:id. |
| `filters.itemId` | string | no | Limits results to transfer orders that have a line for this item. See id on GET inventory/items/:id. The collection GET inventory/warehouse-transfer-orders cannot filter by item, because it does not return the lines. |
| `filters.referenceNumber` | string | no | Limits results to the transfer order with this reference. The match is exact. |
| `filters.fromDate` | date | no | Limits results to transfer orders dated on or after this date. Omit for an open-ended start. Format YYYY-MM-DD. |
| `filters.toDate` | date | no | Limits results to transfer orders dated on or before this date. Omit for an open-ended end. Format YYYY-MM-DD. |
| `filters.modifiedSince` | date-time | no | Limits results to transfer orders whose record changed on or after this time, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `page` | object | no | Pagination controls. Omit for the first page. Example: `{"size":50}`. |
| `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 transfer orders per page. Defaults to 50, capped at 200. |

```json
{
  "filters": {
    "documentStatus": "DRAFT",
    "targetLocationId": "e94a17c3-5b28-4d60-91f7-3a8c2e05b6d1"
  },
  "page": {
    "size": 50
  }
}
```

## Response

`200` Success

Under `data` (searchTransferOrdersOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The transfer orders that match, oldest first, each with its lines. An empty array when nothing matches. Example: `[{"id":"7c1e5a90-3d24-4f68-b0a7-91e5d2c46f38","documentNumber":"WTO-1043","documentStatus":"DRAFT","documentDate":"2026-08-18","lineCount":1,"openLineCount":1,"lastModifiedDate":"2026-08-18T09:14:22.517Z","lines":[{"id":"2d5b81f7-4c93-4a16-8e70-5f1c9d3a82b4","itemCode":"WIDGET-01","quantity":"40","status":"DRAFT"}]}]`. |
| `items[].id` | string | yes | The unique identifier for the transfer order. |
| `items[].documentNumber` | string | no | The transfer order's number, for example 'WTO-1043'. |
| `items[].documentStatus` | string | yes | The status of the transfer order, computed from the lines and set by no endpoint directly. Possible values: 'DRAFT', 'IN_TRANSFER', 'PARTIALLY_PROCESSED', 'PROCESSED'. 'DRAFT' while the order is being written, 'IN_TRANSFER' while a transfer created from it has yet to commit, 'PARTIALLY_PROCESSED' once a transfer has moved part of what was asked for and a remainder is still open, and 'PROCESSED' once nothing is open. |
| `items[].documentDate` | date | no | The date the transfer order is dated. Format YYYY-MM-DD. |
| `items[].referenceNumber` | string | no | Your own reference on the transfer order. |
| `items[].entityId` | string | no | The legal entity the transfer order belongs to. See id on GET base/entities. |
| `items[].entityName` | string | no | The name of that legal entity. |
| `items[].locationId` | string | no | The warehouse the goods leave, where the order names one for the whole document. A line may name its own. 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[].notes` | string | no | Free text on the document. |
| `items[].lineCount` | number | no | The number of lines on the transfer order. |
| `items[].openLineCount` | number | no | How many lines still have quantity left to transfer. Zero means everything has been taken. |
| `items[].createdDate` | date-time | no | The date and time the transfer order was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | date-time | no | The date and time the transfer order record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lines` | array<object> | no | The lines of the transfer order. |
| `items[].lines[].id` | string | yes | The unique identifier for the line. updateLines and deleteLines address a line by it. |
| `items[].lines[].itemId` | string | no | The item to move. 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. See id on GET inventory/warehouses/:id. Absent while no source warehouse has been resolved, and such a line blocks the conversion. |
| `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 to move, in the line's unit. Always greater than zero. |
| `items[].lines[].inventoryQuantity` | decimal | no | The same amount in the item's stocking unit, which is what the warehouse counts. |
| `items[].lines[].openQuantity` | decimal | no | How much of the line is still to be transferred. |
| `items[].lines[].processedQuantity` | decimal | no | How much of the line a transfer has already taken. |
| `items[].lines[].status` | string | no | The state of the line. 'NEEDS_SOURCE' means no source warehouse has been resolved, and the transfer order cannot be converted until it is. |
| `items[].lines[].notes` | string | no | Free text on the line. |
| `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 | no | Whether more results remain beyond this page. |

```json
{
  "data": {
    "items": [
      {
        "id": "7c1e5a90-3d24-4f68-b0a7-91e5d2c46f38",
        "documentNumber": "WTO-1043",
        "documentStatus": "DRAFT",
        "documentDate": "2026-08-18",
        "lineCount": 1,
        "openLineCount": 1,
        "lastModifiedDate": "2026-08-18T09:14:22.517Z",
        "lines": [
          {
            "id": "2d5b81f7-4c93-4a16-8e70-5f1c9d3a82b4",
            "itemCode": "WIDGET-01",
            "quantity": "40",
            "status": "DRAFT"
          }
        ]
      }
    ],
    "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