# List users

`GET /users`

- Base: `GET https://portal.watcheye.com.au/api/v1/users`

List all users on the account.

## Filters

The following filters can be applied to the users list:

- enabled: Whether the user is enabled

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `page` | query | integer | The page number to return Example: `1` |
| `per_page` | query | integer | The number of users per page (defaults to 30, max 500) Example: `30` |
| `enabled` | query | boolean | Only return enabled users * `true` - Only return enabled users * `false` - Only return disabled users Note: The API will accept the string 'true' or the number 1 for true and the string 'false' or the number 0 for false as well as the boolean values. Example: `true` |

## Responses

### 200 Users list response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects | An array of users |
| `data[].uuid` | string (uuid) | The user's UUID Example: `123e4567-e89b-12d3-a456-426614174000` |
| `data[].username` | string | The user's username Example: `jenny.doe@example` |
| `data[].first_name` | string | The user's first name Example: `Jenny` |
| `data[].last_name` | string | The user's last name Example: `Doe` |
| `data[].email` | string | The user's email address Example: `jenny.doe@example.com` |
| `data[].phone` | string | The user's phone number Example: `0412345678` |
| `data[].enabled` | boolean | Whether the user is enabled Example: `true` |
| `data[].roles` | array of strings | The user's roles * `account_manager` - Account Manager * `security_manager` - Security Functions (update SAML settings and related security settings) * `vpn_access` - VPN Access (Permits access from known VPN connections) Note: This will be an empty array if the user has no special roles assigned to them. |
| `data[].last_login_at` | string (date-time) or null | The user's last login timestamp (ISO 8601 format) Example: `2021-01-01T00:00:00Z` |
| `data[].created_at` | string (date-time) | The user's creation timestamp (ISO 8601 format) Example: `2021-01-01T00:00:00Z` |
| `data[].updated_at` | string (date-time) | The user's last update timestamp (ISO 8601 format) Example: `2021-01-01T00:00:00Z` |
| `meta` | object | Metadata about the users list |
| `meta.current_page` | integer | The current page number Example: `1` |
| `meta.per_page` | integer | The number of users per page Example: `10` |
| `meta.total` | integer | The total number of users Example: `1` |
| `meta.last_page` | integer | The last page number Example: `10` |
| `api_reference` | string (uuid) | A unique identifier for this request. This can be used to track the request in the logs and audit trail. Example: `123e4567-e89b-12d3-a456-426614174000` |

**Sample response**

```json
{
    "data": [
        {
            "uuid": "123e4567-e89b-12d3-a456-426614174000",
            "username": "jenny.doe@example",
            "first_name": "Jenny",
            "last_name": "Doe",
            "email": "jenny.doe@example.com",
            "phone": "0412345678",
            "enabled": true,
            "roles": [
                "account_manager"
            ],
            "last_login_at": "2021-01-01T00:00:00Z",
            "created_at": "2021-01-01T00:00:00Z",
            "updated_at": "2021-01-01T00:00:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 10,
        "total": 1,
        "last_page": 10
    },
    "api_reference": "123e4567-e89b-12d3-a456-426614174000"
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))