---
title: "Query zones"
method: POST
path: "/v1/zones/query"
tags: ["Zones"]
---

# Query zones

`POST /v1/zones/query`

Return full zone details for many zones in a single call. Filter by `ids` and/or `externalIds` (combined with OR); omit both to page through all of the organization's zones. Results come back under `data` with pagination under `meta`; each `data` item matches the shape of `GET /v1/zones/<id>`.

## Request body

- ZonesQueryRequest — Body for `POST /v1/zones/query`. `ids` and `externalIds` are optional and combined with OR. Omit both to page through every zone in the organization; a provided but empty list matches nothing.
  - `ids` string[], nullable — Nash zone ids to fetch (max 500). Combined with `externalIds` using OR. Omit to not filter by id; an empty list matches nothing.
  - `externalIds` string[], nullable — Your external zone ids to fetch (max 500). Combined with `ids` using OR. Omit to not filter by external id; an empty list matches nothing.
  - `isDeleted` boolean — When true, return soft-deleted zones instead of active ones.
  - `size` integer — Page size, 1 to 500. Requests above 500 return a ZONE_BULK_LIMIT_EXCEEDED error.
  - `offset` integer — Number of zones to skip, for paging through the full result set.

## Response `200`

OK

- ZonesQueryResponse — Paginated zones, in created-at order. `data` items match `GET /v1/zones/<id>`.
  - `data` ZoneDetailRead[], required — Rows for this page, in a deterministic order.
    - `id` string, required — Nash zone id.
    - `name` string, nullable — Zone name.
    - `externalId` string, nullable — Your external id for the zone.
    - `portalUrl` string, nullable — Nash portal URL for the zone.
    - `coverageArea` ZoneCoverageAreaRead
      - `id` string, required — Nash coverage area id.
      - `cityZipcodes` string[], nullable — City and zip code pairs covered.
      - `zipCodes` string[], nullable — Zip codes covered.
      - `cities` string[], nullable — Cities covered.
      - `states` string[], nullable — States or regions covered.
      - `countries` string[], nullable — Two-letter ISO country codes covered.
      - `polygons` ZonePolygonRead[] — Geometry boundaries attached to this coverage area.
        - `id` string, required — Nash polygon id.
        - `polygonData` array[], nullable — Closed ring of [latitude, longitude] coordinate pairs defining the boundary.
          - number[]
    - `storeLocations` ZoneStoreLocationRead[] — Store locations associated with the zone.
      - `id` string, required — Nash store location id.
      - `externalId` string, nullable — Your external id for the store location.
      - `name` string, nullable — Store location name.
      - `firstName` string, nullable — Contact first name.
      - `lastName` string, nullable — Contact last name.
      - `phoneNumber` string, nullable — Contact phone number.
      - `email` string, nullable — Contact email.
      - `pickupInstructions` string, nullable — Pickup instructions for couriers.
      - `prepTimeMinutes` integer, nullable — Order preparation time in minutes.
      - `blackoutDates` string[], nullable — Dates (YYYY-MM-DD) the store is closed.
      - `operatingHours` object, nullable — Per-weekday opening hours, keyed by day name.
      - `tags` string[], nullable — Free-form tags on the store location.
      - `location` ZoneLocationRead
        - `address` string, nullable — Single-line formatted address of the store location.
        - `addressFirstLine` string, nullable — Street line of the address.
        - `addressSecondarynumber` string, nullable — Secondary number (unit, suite) if any.
        - `addressCity` string, nullable — City.
        - `addressCountry` string, nullable — Two-letter ISO country code.
        - `addressState` string, nullable — State or region.
        - `addressZip` string, nullable — Postal code.
        - `lat` number, nullable — Latitude.
        - `lng` number, nullable — Longitude.
    - `storeLocationAssociations` ZoneStoreLocationAssociationRead[] — Store-location links with optional active date ranges.
      - `storeLocationId` string, required — Nash id of the associated store location.
      - `startDate` string, date-time, nullable — Start of the window during which the association is active (null = always).
      - `endDate` string, date-time, nullable — End of the window during which the association is active (null = open-ended).
    - `tags` string[], nullable — Free-form tags on the zone.
    - `zoneMetadata` object, nullable — Arbitrary key-value metadata stored on the zone.
    - `isDeleted` boolean, nullable — Whether the zone is soft-deleted.
  - `meta` PageMeta, required — Offset-pagination metadata for a single page of a query response.
    - `total` integer, required — Total rows matching the filter across all pages, ignoring size and offset.
    - `size` integer, required — Page size used for this response.
    - `offset` integer, required — Offset used for this response.

## Other responses

- `422` — Unprocessable Content

---

[API](https://skmtc.net/usenash/apis/nash-api.md) · [All operations](https://skmtc.net/usenash/apis/nash-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usenash/nash-api/revisions/09a23a95889b/schema)