# Get Locations

`GET /api/v1/locations`

Retrieves a paginated list of Location 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 (prefix with `-` for descending). Default: name. |
| `include` | string | no | Comma-separated. Allowed: locationCategory, district, district2, locationGroups. |

## Example request

```bash
curl "https://app.franchisesee.com/api/v1/locations" \
  -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": "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": {
                    "id": "e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90",
                    "name": "Region",
                    "index": 1,
                    "created_at": "2025-03-14T15:22:08.000000Z",
                    "updated_at": "2026-10-02T09:41:55.000000Z"
                }
            },
            "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": {
                    "id": "e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90",
                    "name": "Region",
                    "index": 1,
                    "created_at": "2025-03-14T15:22:08.000000Z",
                    "updated_at": "2026-10-02T09:41:55.000000Z"
                }
            },
            "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": {
                    "id": "e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90",
                    "name": "Region",
                    "index": 1,
                    "created_at": "2025-03-14T15:22:08.000000Z",
                    "updated_at": "2026-10-02T09:41:55.000000Z"
                }
            },
            "locationGroups": [
                {
                    "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": [
                        {}
                    ]
                }
            ]
        }
    ]
}
```

### 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."
}
```
