---
title: "Filter locations"
method: GET
path: "/locations/filter"
tags: ["Locations"]
---

# Filter locations

`GET /locations/filter`

## Request

- Base URL: `https://api.synup.com/api/v4`
- URL: `https://api.synup.com/api/v4/locations/filter`
- Auth: none required
- TypeScript: <https://skmtc.dev/synup/apis/synup-api/docs/locations/filter/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns a paginated list of locations that match the supplied filters.

The filter criteria are passed as a single JSON-encoded object in the `input` query parameter. Supported filter keys include name/store/phone search (`query`, `storeId`, `phone`), location identifiers (`ids`), package tier (`package`), `tags`, `folders`, `categories`, address filters (`postalCode`, `city`, `stateIso`), custom attributes (`customAttributes`), GBP categories (`primaryGbpSiteCategories`, `additionalGbpSiteCategories`), add-ons (`addOnIds`), Google verification status (`googleVerificationStatus`), and client account scoping (`clientIds`).

Results are returned as a Relay-style connection (`edges` + `pageInfo`). Use the `first`/`after` (or `last`/`before`) parameters to page through results.

## Query parameters

- `input` string
- `first` integer
- `after` string
- `last` integer
- `before` string
- `archived` boolean
- `approved` boolean
- `hasErrors` boolean
- `archivalScheduledAt` boolean
- `blacklistIds` string[]
- `sortByNameAsc` boolean

## Headers

- `Synup-Version` string, required
- `Authorization` string, required

## Response `200`

Successful response

- object
  - `data` object
    - `filterLocations` LocationSummaryConnectionType
      - `edges` LocationSummaryEdgeV2[]
        - `cursor` string
        - `node` string
      - `nodes` string[]
      - `pageInfo` PageInfoV2
        - `hasNextPage` boolean: Indicates if there are more pages available
        - `hasPreviousPage` boolean: Indicates if there are previous pages available
        - `totalPages` integer: Total number of pages available
        - `totalRecords` integer: Total number of records across all pages
      - `totalCount` integer: Total number of records matching the filter.

## Other responses

- `400`: Bad request - Invalid filter or parameters
- `401`: Unauthorized - Invalid or missing API key

---

[API](https://skmtc.dev/synup/apis/synup-api.md) - [All operations](https://skmtc.dev/synup/apis/synup-api/llms.txt) - [OpenAPI document](https://skmtc.dev/synup/apis/synup-api/revisions/67de2d51c22e?raw)