# Returns the warehouse transfer orders that match the given filters.

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

Group: Inventory › Warehouse Transfer Orders · Operation ID: `searchTransferOrders`

Searches warehouse transfer orders by exact criteria in the request body, and returns the same item schema as GET inventory/warehouse-transfer-orders/:id, lines included. It is a query: it answers 200 and writes nothing.

itemId is accepted here and nowhere else. It matches orders that have a line for that item, the question the collection cannot answer, because the lines are not on it. referenceNumber is accepted here rather than on the collection, because a query string is logged and it identifies someone else's transaction.

An identifier that resolves to nothing returns an empty page, not an error.

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

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

Example:

```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 of object | yes | The transfer orders that match, oldest first, each with its lines. An empty array when nothing matches. |
| `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` | string (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` | string (date-time) | no | The date and time the transfer order was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | string (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 of 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. There is no endpoint for it. |
| `items[].lines[].unitCode` | string | no | The code of that unit. |
| `items[].lines[].quantity` | string (decimal) | no | How much to move, in the line's unit. Always greater than zero. |
| `items[].lines[].inventoryQuantity` | string (decimal) | no | The same amount in the item's stocking unit, which is what the warehouse counts. |
| `items[].lines[].openQuantity` | string (decimal) | no | How much of the line is still to be transferred. |
| `items[].lines[].processedQuantity` | string (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. |
| `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. |

## 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