# Filter locations

```http
GET https://api.synup.com/api/v4/locations/filter
```

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.

Source: https://developer.synup.com/api/locations/filter-locations

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | string | optional | JSON-encoded filter object. See the description for supported keys. Defaults to an empty filter (all locations). |
| `first` | integer | optional | Number of records to return from the start of the result set. |
| `after` | string | optional | Cursor to fetch records after. |
| `last` | integer | optional | Number of records to return from the end of the result set. |
| `before` | string | optional | Cursor to fetch records before. |
| `archived` | boolean | optional | Filter by archived state (true/false). |
| `approved` | boolean | optional | Filter by approved state (true/false). |
| `hasErrors` | boolean | optional | Return only locations that currently have errors. |
| `archivalScheduledAt` | boolean | optional | Return only locations scheduled for archival. |
| `blacklistIds` | array | optional | Location IDs to exclude from the result set. |
| `sortByNameAsc` | boolean | optional | Sort results by location name ascending. |

## Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Synup-Version` | string | required | API version date (YYYY-MM-DD). |

## Example request

```bash
curl -X GET 'https://api.synup.com/api/v4/locations/filter' \
  -H 'Authorization: API YOUR_API_KEY' \
  -H 'Content-Type: application/json'
```

## Responses

| Status | Description |
| --- | --- |
| `200` | Successful response |
| `400` | Bad request - Invalid filter or parameters |
| `401` | Unauthorized - Invalid or missing API key |