# Get Users

`GET /api/v1/users`

Retrieves a paginated list of User objects. Requires the `read` ability. HQ tokens list every user in the brand; a franchisee token lists the users at its own location, or only itself when it reaches stores through location groups.

## 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[email]` | string | no |  |
| `filter[perspective]` | string | no |  |
| `sort` | string | no | Allowed: first_name, last_name, email, created_at, updated_at. Default: email. |
| `include` | string | no | Allowed: locationGroups, location. |

## Example request

```bash
curl "https://app.franchisesee.com/api/v1/users" \
  -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": "6e2b9d41-8c7a-4f3e-b1d5-9a0c2e4f6b81",
            "first_name": "Jordan",
            "last_name": "Rivera",
            "email": "jordan.rivera@example.com",
            "perspective": "admin",
            "location_id": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e",
            "has_sso_auth": true,
            "roles": [
                "string"
            ],
            "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": [
                        {}
                    ]
                }
            ],
            "location": {
                "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."
}
```
