# Search warehouses

Operation ID: `searchWarehouses`

Group: Inventory › Warehouses

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

`POST /inventory/warehouses/search`

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

Searches warehouses. This endpoint can filter by name, city, countryCode, and region, which the collection GET inventory/warehouses can't. These filters match exactly, not on part of the text.

The fields are the same as on GET inventory/warehouses/:id.

## 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`: 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. Example: `{"entityId":"3f9c1e28-7b45-4d60-a913-5e07c286bd41","isActive":true,"inventoryLocationType":"WAREHOUSE"}`. |
| `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` | any | no | Limits results to warehouses of this kind of location. It is also available as filter[inventoryLocationType] on the collection. One of: `"WAREHOUSE"`, `"STORE"`, `"VIRTUAL_QC"`, `"VIRTUAL_RECEIVING"`, `"VIRTUAL_SHIPPING"`, `"EXTERNAL_3PL"`, `"EXTERNAL_CONSIGNMENT"`. |
| `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` | 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. 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 warehouses per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

```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<object> | yes | The warehouses on this page, ordered by id. An empty array when nothing matches. Example: `[{"id":"e1d84c07-5b39-4a26-9f70-2c8b613ad495","locationCode":"WH-01","entityId":"81e8beb1-1415-4012-9012-8138580f43dc","entityName":"Acme GmbH","name":"Rotterdam Distribution Centre","inventoryLocationType":"WAREHOUSE","isActive":true,"isPrimaryReceiving":true,"addressLine1":"Waalhaven 12","city":"Rotterdam","postalCode":"3087 BM","countryCode":"NL","region":"Benelux","lastModifiedDate":"2026-08-03T11:15:00.000Z"}]`. |
| `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` | any | yes | The kind of location. One of: `"WAREHOUSE"`, `"STORE"`, `"VIRTUAL_QC"`, `"VIRTUAL_RECEIVING"`, `"VIRTUAL_SHIPPING"`, `"EXTERNAL_3PL"`, `"EXTERNAL_CONSIGNMENT"`. |
| `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` | 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. 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 warehouses remain beyond this page. |

```json
{
  "data": {
    "items": [
      {
        "id": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
        "locationCode": "WH-01",
        "entityId": "81e8beb1-1415-4012-9012-8138580f43dc",
        "entityName": "Acme GmbH",
        "name": "Rotterdam Distribution Centre",
        "inventoryLocationType": "WAREHOUSE",
        "isActive": true,
        "isPrimaryReceiving": true,
        "addressLine1": "Waalhaven 12",
        "city": "Rotterdam",
        "postalCode": "3087 BM",
        "countryCode": "NL",
        "region": "Benelux",
        "lastModifiedDate": "2026-08-03T11:15:00.000Z"
      }
    ],
    "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