# Get Location Groups

`GET /api/v1/location-groups`

Retrieves a paginated list of LocationGroup objects. Requires the `read` ability.

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `page[number]` | integer | no | Page number (starts at 1). |
| `page[size]` | integer | no | Results per page (default 30, max 100). |
| `filter[external_id]` | string | no |  |
| `sort` | string | no | Allowed: name, created_at, updated_at. Default: name. |
| `include` | string | no | Allowed: locations. |

## Example request

```bash
curl "https://app.franchisesee.com/api/v1/location-groups" \
  -H "Authorization: Bearer $FRANCHISESEE_TOKEN" \
  -H "Accept: application/json"
```

## Responses

### 200 Success

```json
{
    "links": {
        "first": "https://app.franchisesee.com/api/v1/locations?page[number]=1",
        "last": "https://app.franchisesee.com/api/v1/locations?page[number]=10",
        "prev": "https://app.franchisesee.com/api/v1/locations?page[number]=1",
        "next": "https://app.franchisesee.com/api/v1/locations?page[number]=3"
    },
    "meta": {
        "current_page": 2,
        "from": 26,
        "last_page": 10,
        "path": "https://app.franchisesee.com/api/v1/locations",
        "per_page": 25,
        "to": 50,
        "total": 250
    },
    "data": [
        {
            "id": "a3c5e7f9-2b4d-4f6a-8c1e-3d5f7a9b1c20",
            "name": "Austin Metro",
            "external_id": "AUS-METRO",
            "created_at": "2025-03-14T15:22:08.000000Z",
            "updated_at": "2026-10-02T09:41:55.000000Z",
            "locations": [
                {
                    "id": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e",
                    "external_id": "STR-1042",
                    "name": "Downtown Austin",
                    "address": "401 Congress Ave",
                    "city": "Austin",
                    "region": "TX",
                    "postal_code": "78701",
                    "country": "US",
                    "timezone": "America/Chicago",
                    "timezone_source": "pos",
                    "is_private": false,
                    "is_corporate": false,
                    "is_active": true,
                    "activation_status": "active",
                    "deactivated_at": null,
                    "is_deletable": false,
                    "deletable_on": null,
                    "district_id": "3f2a1b0c-9d8e-4f7a-b6c5-d4e3f2a1b0c9",
                    "district_id_2": "c7e9a2d4-1b3f-4e8a-9c6d-5f2e8b1a7d30",
                    "location_category_id": "5d8e2f1a-6c4b-4a9e-8f3d-2b7c1e9a4d60",
                    "created_at": "2025-03-14T15:22:08.000000Z",
                    "updated_at": "2026-10-02T09:41:55.000000Z",
                    "datasource_settings": {
                        "qu": {
                            "location_id": 12345
                        },
                        "brink": {
                            "api_key_set": true
                        }
                    },
                    "district": {
                        "id": "3f2a1b0c-9d8e-4f7a-b6c5-d4e3f2a1b0c9",
                        "name": "Central Texas",
                        "external_id": "CTX",
                        "district_group_id": "e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90",
                        "created_at": "2025-03-14T15:22:08.000000Z",
                        "updated_at": "2026-10-02T09:41:55.000000Z",
                        "districtGroup": {}
                    },
                    "district2": {
                        "id": "3f2a1b0c-9d8e-4f7a-b6c5-d4e3f2a1b0c9",
                        "name": "Central Texas",
                        "external_id": "CTX",
                        "district_group_id": "e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90",
                        "created_at": "2025-03-14T15:22:08.000000Z",
                        "updated_at": "2026-10-02T09:41:55.000000Z",
                        "districtGroup": {}
                    },
                    "locationCategory": {
                        "id": "5d8e2f1a-6c4b-4a9e-8f3d-2b7c1e9a4d60",
                        "name": "Inline",
                        "external_id": "INLINE",
                        "location_category_group_id": "f2b6d8a1-4c3e-4e7b-a5d9-1c8e3f6b2a40",
                        "sort_order": 1,
                        "created_at": "2025-03-14T15:22:08.000000Z",
                        "updated_at": "2026-10-02T09:41:55.000000Z",
                        "locationCategoryGroup": {}
                    },
                    "locationGroups": [
                        {}
                    ]
                }
            ]
        }
    ]
}
```

### 401 Authentication failed or missing.

```json
{
    "message": "Unauthenticated."
}
```

### 403 The token lacks the required ability or the caller is not permitted.

```json
{
    "message": "This API token does not have the 'create' ability."
}
```
