# Personal Account API

Source: https://userguide.qualytics.io/settings/access/users/api/

The Personal Account API allows administrators to list, update, deactivate, and restore user accounts programmatically.

> **Tip**
>
> For complete API documentation, including request/response schemas, visit the [API docs](https://userguide.qualytics.io/api/docs).

All endpoints use the base URL of your Qualytics deployment (e.g., `https://your-instance.qualytics.io/api`).

> **Note**
>
> There is no direct create operation for Personal Accounts. Accounts are created through an [email invitation](https://userguide.qualytics.io/settings/access/sign-in-providers/how-tos/invite-user/), a first sign-in through a [sign-in provider](https://userguide.qualytics.io/settings/access/sign-in-providers/introduction/), or [Directory Sync (SCIM)](https://userguide.qualytics.io/settings/access/directory-sync/introduction/). The invitation endpoints are documented on the [Sign-In Providers API](https://userguide.qualytics.io/settings/access/sign-in-providers/api/) page.

---

## List Users

Retrieve a paginated list of users with optional filters.

**Endpoint:**

```bash
GET /api/users
Authorization: Bearer {token}
```

**Query Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| `sort_name` | string | Sort by name (`asc` or `desc`) |
| `sort_created` | string | Sort by creation date (`asc` or `desc`) |
| `sort_team` | string | Sort by team (`asc` or `desc`) |
| `sort_status` | string | Sort by status (`asc` or `desc`) |
| `sort_role` | string | Sort by role (`asc` or `desc`) |
| `sort_type` | string | Sort by user type (`asc` or `desc`) |
| `sort_last_login` | string | Sort by last sign-in (`asc` or `desc`) |
| `name` | string | Filter by user name or email (partial match, case-insensitive) |
| `role` | string | Filter by role (`Admin`, `Manager`, `Member`) |
| `team` | string | Filter by team name |
| `type` | string | Filter by user type (`Human`, `Service`) |
| `include_deleted` | boolean | Include deactivated users in results |
| `filters` | `string` (JSON) | Narrows the list by one or more filters, written as a JSON object. See [Filtering Lists](https://userguide.qualytics.io/settings/access/users/api/#filtering-lists). |

**Required Role:** Manager or Admin

> **Tip: Reviewing identity provider groups**
>
> For accounts that sign in through an OIDC or SAML identity provider, each user in the response carries an `oidc_groups` field holding the group names that provider presented at the user's last sign-in. The field keeps its original name for both provider types, and the names are recorded in lowercase, so they will not always match the casing the provider sent. Compare it against the user's `teams` to audit group-based Team membership. To review one account instead, the same listing appears as the **Identity Provider Groups** field in the [Edit User dialog](https://userguide.qualytics.io/settings/access/users/how-tos/edit-user/). See [Just-in-Time Provisioning and Group Sync](https://userguide.qualytics.io/deployments/idp-group-sync/).

### Filtering Lists

`GET /api/users` accepts a `filters` parameter: a JSON object with one entry per filter, saying how that filter's values should match.

```bash
curl -G "https://your-instance.qualytics.io/api/users" \
  --data-urlencode 'filters={"role":{"not_in":["Admin"]}}' \
  -H "Authorization: Bearer YOUR_TOKEN"
```

This returns the users who aren't Admins.

| Key | Returns |
| --- | --- |
| `in` | The items that match at least one of the values. |
| `not_in` | The items that match none of the values. |
| `all_of` | The items that match every value, on filters an item can have several of, such as tags. |
| `empty` | The items with no value (`true`) or at least one (`false`), on filters an item can lack. |

- Different filters combine with AND, and so do keys on the same filter.
- `empty` can't be combined with other keys on the same filter.
- A filter sent both as its own parameter and inside `filters` returns a `422`. Put all of that filter's conditions in `filters`.
- `in`, `not_in` and `all_of` each take between 1 and 20 values.
- A filter or key the endpoint doesn't accept returns a `422` that names it. The [API docs](https://userguide.qualytics.io/api/docs) list what each endpoint accepts.

---

## Get User

Retrieve a single user by ID.

**Endpoint:**

```bash
GET /api/users/{id}
Authorization: Bearer {token}
```

**Required Role:** Manager or Admin

---

## Update User

Update a user's role or team assignments.

**Endpoint:**

```bash
PUT /api/users/{id}
Authorization: Bearer {admin_token}
Content-Type: application/json
```

**Request Body:**

```json
{
  "role": "Manager",
  "teams": ["Data Engineering", "Data Quality"]
}
```

`teams` replaces the user's current team assignments, and the **Public** team is always kept. Names must match an existing team exactly, including case. A name that matches no team creates a new team with the **Viewer** team permission.

**Required Role:** Admin

---

## Deactivate User

Soft-delete a user account. The user can no longer log in but their account can be restored later.

**Endpoint:**

```bash
DELETE /api/users/{id}
Authorization: Bearer {admin_token}
```

**Required Role:** Admin

---

## Reactivate User

Restore a previously deactivated user account.

**Endpoint:**

```bash
PATCH /api/users/{id}
Authorization: Bearer {admin_token}
```

**Required Role:** Admin

---

## Get Current User

Retrieve the currently authenticated user's information.

**Endpoint:**

```bash
GET /api/users/me
Authorization: Bearer {token}
```

**Required Role:** Member or above

*Last updated: October 15, 2026.*
