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

# Query zones

`POST /v1/zones/query`

## Request

- Base URL: `https://api.sandbox.usenash.com`
- URL: `https://api.sandbox.usenash.com/v1/zones/query`
- Auth: none declared

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.dev/nash/apis/nash-api.md) - [All operations](https://skmtc.dev/nash/apis/nash-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nash/apis/nash-api/revisions/e3713837c5c9?raw)