# Returns the warehouses that match the given filters.

`POST /inventory/warehouses/search`

Group: Inventory › Warehouses · Operation ID: `searchWarehouses`

Every criterion is exact and criteria combine with AND. There is no free-text or substring search. This endpoint accepts the filters that must not appear in a URL: name, city, countryCode and region. entityId, warehouseTypeId, inventoryLocationType, isActive, isPrimaryReceiving and locationCode are also accepted here and share the names they have on GET inventory/warehouses. An identifier matching nothing returns an empty page, not an error.

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

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A warehouse must match every filter you send. Send an empty object to return all warehouses. |
| `filters.locationCode` | string | no | Limits results to the warehouse with this location code. The match is exact. Codes are unique, so this matches at most one warehouse. |
| `filters.name` | string | no | Limits results to the warehouse with this site name. The match is exact. This filter is available only here, not on the collection. |
| `filters.entityId` | string | no | Limits results to the warehouses owned by the legal entity with this identifier. An identifier matching no entity returns an empty page, not an error. See id on GET base/entities. |
| `filters.warehouseTypeId` | string | no | Limits results to the warehouses assigned to the warehouse type with this identifier. An identifier matching no warehouse type returns an empty page. There is no endpoint for it. |
| `filters.inventoryLocationType` | string, one of `"WAREHOUSE"`, `"STORE"`, `"VIRTUAL_QC"`, `"VIRTUAL_RECEIVING"`, `"VIRTUAL_SHIPPING"`, `"EXTERNAL_3PL"`, `"EXTERNAL_CONSIGNMENT"` | no | Limits results to warehouses of this kind of location. It is also available as filter[inventoryLocationType] on the collection. |
| `filters.isActive` | boolean | no | Limits results to warehouses that can be selected on new documents when true, or to retired ones when false. Omit to match both. |
| `filters.isPrimaryReceiving` | boolean | no | Limits results to each entity's primary receiving warehouse when true, or excludes it when false. Omit to match both. |
| `filters.city` | string | no | Limits results to warehouses in this city. The match is exact. This filter is available only here, not on the collection. |
| `filters.countryCode` | string | no | Limits results to warehouses in this country. Format ISO 3166-1 alpha-2, for example 'NL'. The match is exact. This filter is available only here, not on the collection. |
| `filters.region` | string | no | Limits results to warehouses in this business region grouping. The match is exact. This filter is available only here, not on the collection. |
| `filters.modifiedSince` | string (date-time) | no | Limits results to warehouses changed on or after this time. 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 for the first page. |
| `page.size` | number | no | The number of warehouses per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

Example:

```json
{
  "filters": {
    "entityId": "3f9c1e28-7b45-4d60-a913-5e07c286bd41",
    "isActive": true,
    "inventoryLocationType": "WAREHOUSE"
  },
  "page": {
    "size": 50
  }
}
```

## Response

`200` Success

Under `data` (searchWarehousesOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The warehouses on this page, ordered by id. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the warehouse. |
| `items[].locationCode` | string | yes | The location code of the warehouse, for example 'WH-01'. It is unique within the tenant. |
| `items[].entityId` | string | yes | The unique identifier for the legal entity that owns this warehouse. See id on GET base/entities. |
| `items[].entityName` | string | no | The name of the legal entity that owns this warehouse. |
| `items[].warehouseTypeId` | string | no | The unique identifier for the warehouse type, which limits the document types the warehouse allows. Absent when the warehouse allows every type. There is no endpoint for it. |
| `items[].warehouseTypeName` | string | no | The name of the warehouse type. Absent when the warehouse allows every document type. |
| `items[].name` | string | yes | The site name of the warehouse, for example 'Rotterdam Distribution Center'. |
| `items[].inventoryLocationType` | string, one of `"WAREHOUSE"`, `"STORE"`, `"VIRTUAL_QC"`, `"VIRTUAL_RECEIVING"`, `"VIRTUAL_SHIPPING"`, `"EXTERNAL_3PL"`, `"EXTERNAL_CONSIGNMENT"` | yes | The kind of location. |
| `items[].isActive` | boolean | yes | Whether the warehouse can be selected on new inventory documents. When false, existing stock and history keep pointing at it and new documents cannot select it. |
| `items[].isPrimaryReceiving` | boolean | no | Whether this is the entity's primary receiving warehouse. Open purchase-order on-order quantity for the entity is attributed here for replenishment. At most one warehouse per entity is the primary receiving warehouse. |
| `items[].addressLine1` | string | no | The first address line: street number and name, or PO box. Absent when unset. |
| `items[].addressLine2` | string | no | The second address line: apartment, suite, unit, building or floor. Absent when unset. |
| `items[].city` | string | no | The city or locality. Absent when unset. |
| `items[].stateProvince` | string | no | The state, province or region. Absent when unset. |
| `items[].postalCode` | string | no | The postal or ZIP code. Absent when unset. |
| `items[].countryCode` | string | no | The country of the address. Format ISO 3166-1 alpha-2, for example 'NL'. Absent when unset. |
| `items[].region` | string | no | A free-text business region grouping, independent of country and state. Absent when unset. |
| `items[].lastModifiedDate` | string (date-time) | no | The date and time the warehouse record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `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 | yes | True when more warehouses 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