# Users

## Model Definition

**Alias**

`user`

**Relations**

| Relation                                                  | Key                 | Type            | Relation Field(s)                                                                    |
| --------------------------------------------------------- | ------------------- | --------------- | ------------------------------------------------------------------------------------ |
| [Language](/api-reference/languages.md)                   | `language`          | Belongs to      | `lang_id`                                                                            |
| [Role](/api-reference/roles.md)                           | `role`              | Belongs to      | `role_id`                                                                            |
| TermsOfUse                                                | `acceptedPolicies`  | Belongs to many | `terms_of_use_accepted_users.user_id`, `terms_of_use_accepted_users.terms_of_use_id` |
| [EntityPermissions](/api-reference/entity-permissions.md) | `entityPermissions` | Morph many      | `entity_permissions.permission_entity`, `entity_permissions.permission_entity_id`    |

**Computed Properties**

* `full_name` - Concatenated from `first_name` and `last_name`
* `online` - Whether the `User` is online

## List

Get a list of all `Users`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/users`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/users', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 3,
    "username": "usergroup.01",
    "first_name": "",
    "last_name": "",
    "active": true,
    "group_account": true,
    "role_id": 2,
    "profile_picture": null,
    "street": null,
    "zipcode": null,
    "city": null,
    "email": null,
    "phone": null,
    "birthdate": null,
    "gender": null,
    "entering_date": null,
    "leaving_date": null,
    "staff_number": null,
    "wants_email_notifications": false,
    "created_at": "2016-04-25 11:06:51",
    "updated_at": "2021-06-10 09:11:00",
    "deactivated_at": null,
    "deleted_at": null,
    "blacked_out_at": null,
    "default_route": null,
    "prevent_logout": false,
    "full_name": " "
  },
  {
    "id": 4,
    "username": "usergroup.02",
    "first_name": "",
    "last_name": "",
    "active": true,
    "group_account": true,
    "role_id": 3,
    "profile_picture": null,
    "street": null,
    "zipcode": null,
    "city": null,
    "email": null,
    "phone": null,
    "birthdate": null,
    "gender": null,
    "entering_date": null,
    "leaving_date": null,
    "staff_number": null,
    "wants_email_notifications": false,
    "created_at": "2016-04-25 11:06:51",
    "updated_at": "2021-06-10 09:11:00",
    "deactivated_at": null,
    "deleted_at": null,
    "blacked_out_at": null,
    "default_route": null,
    "prevent_logout": false,
    "full_name": " "
  }
]
```

## List deleted Users

Get a list of all deleted `Users`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/users/deleted`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/users/deleted', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 3,
    "username": "usergroup.01",
    "first_name": "",
    "last_name": "",
    "active": false,
    "group_account": true,
    "role_id": 2,
    "profile_picture": null,
    "street": null,
    "zipcode": null,
    "city": null,
    "email": null,
    "phone": null,
    "birthdate": null,
    "gender": null,
    "entering_date": null,
    "leaving_date": null,
    "staff_number": null,
    "wants_email_notifications": false,
    "created_at": "2016-04-25 11:06:51",
    "updated_at": "2021-06-10 09:11:00",
    "deactivated_at": null,
    "deleted_at": "2021-06-12 09:13:00",
    "blacked_out_at": null,
    "default_route": null,
    "prevent_logout": false,
    "full_name": " "
  },
  {
    "id": 4,
    "username": "usergroup.02",
    "first_name": "",
    "last_name": "",
    "active": false,
    "group_account": true,
    "role_id": 3,
    "profile_picture": null,
    "street": null,
    "zipcode": null,
    "city": null,
    "email": null,
    "phone": null,
    "birthdate": null,
    "gender": null,
    "entering_date": null,
    "leaving_date": null,
    "staff_number": null,
    "wants_email_notifications": false,
    "created_at": "2016-04-25 11:06:51",
    "updated_at": "2021-06-10 09:11:00",
    "deactivated_at": null,
    "deleted_at": "2021-06-12 09:13:00",
    "blacked_out_at": null,
    "default_route": null,
    "prevent_logout": false,
    "full_name": " "
  }
]
```

## Show

Show a single `User` by `id`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/users/{id}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/users/3', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 3,
  "username": "usergroup.01",
  "first_name": "",
  "last_name": "",
  "active": true,
  "group_account": true,
  "role_id": 2,
  "profile_picture": null,
  "street": null,
  "zipcode": null,
  "city": null,
  "email": null,
  "phone": null,
  "birthdate": null,
  "gender": null,
  "entering_date": null,
  "leaving_date": null,
  "staff_number": null,
  "wants_email_notifications": false,
  "created_at": "2016-04-25 11:06:51",
  "updated_at": "2021-06-10 09:11:00",
  "deactivated_at": null,
  "deleted_at": null,
  "blacked_out_at": null,
  "default_route": null,
  "prevent_logout": false,
  "full_name": " "
}
```

## Show profile picture

Show the content of a `User`'s profile picture by `id`.

**Definition**

<mark style="color:green;">`GET`</mark> `/users/{id}/profile-picture`

{% hint style="warning" %}
This routes content type depends on the profile picture's content disposition retrieved from the filesystem.
{% endhint %}

## Create

Create a new `User`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/users`

**Request Keys**

| Key                         |   Type  | Default | Description                                                                                       |
| --------------------------- | :-----: | :-----: | ------------------------------------------------------------------------------------------------- |
| `username` \*               |  string |    -    | The username of the `User` (min. 4 characters)                                                    |
| `password` \*               |  string |    -    | The password for the `User` (min. 6 characters)                                                   |
| `first_name` \*             |  string |    -    | First name of this `User`                                                                         |
| `last_name` \*              |  string |    -    | Last name of this `User`                                                                          |
| `active`                    | boolean |  `true` | Whether the `User` is active                                                                      |
| `group_account`             | boolean | `false` | Whether the `User` is a Group Account                                                             |
| `role_id` \*                | integer |    -    | Related [Role](/api-reference/roles.md)                                                           |
| `request_password_change`   | boolean |    -    | Whether the password should be changed by the `User` on the next login                            |
| `profile_picture`           |   file  |  `null` | A filestream containing the profile picture                                                       |
| `street`                    |  string |  `null` | Street where the `User` lives at                                                                  |
| `zipcode`                   |  string |  `null` | Zipcode of the city the `User` lives in                                                           |
| `city`                      |  string |  `null` | City where the `User` lives in                                                                    |
| `email`                     |  email  |  `null` | Email of the `User`                                                                               |
| `phone`                     |  string |  `null` | Phone number of the `User`                                                                        |
| `birthday`                  |   date  |  `null` | Birthday of the `User`                                                                            |
| `gender`                    |  string |  `null` | Gender of the `User` (`female` or `male`)                                                         |
| `entering_date`             |   date  |  `null` | Date when the `User` enters/entered the company                                                   |
| `leaving_date`              |   date  |  `null` | Date when the `User` leaves/left the company                                                      |
| `staff_number`              |  string |  `null` | The identification number of the `User` inside a company                                          |
| `wants_email_notifications` | boolean |  `true` | Whether the `User` get's notified about [Notifications](/api-reference/notifications.md) by email |

Keys with `*` are required.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/users', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'username' => 'jeremy.doe',
        'password' => 'jeremy.doe',
        'first_name' => 'Jeremy',
        'last_name' => 'Doe',
        'role_id' => 3
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 5,
    "username": "jeremy.doe",
    "first_name": "Jeremy",
    "last_name": "Doe",
    "active": true,
    "group_account": false,
    "role_id": 3,
    "profile_picture": null,
    "street": null,
    "zipcode": null,
    "city": null,
    "email": null,
    "phone": null,
    "birthdate": null,
    "gender": null,
    "entering_date": null,
    "leaving_date": null,
    "staff_number": null,
    "wants_email_notifications": false,
    "created_at": "2021-11-01 23:39:04",
    "updated_at": "2021-11-01 23:39:04",
    "deactivated_at": null,
    "deleted_at": null,
    "blacked_out_at": null,
    "default_route": null,
    "prevent_logout": false,
    "full_name": "Jeremy Doe"
  }
}
```

## Restore

Restore a deleted `User` by `id`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/users/restore/{id}`

**Request Keys**

| Key       | Type | Default | Description                                                                              |
| --------- | :--: | :-----: | ---------------------------------------------------------------------------------------- |
| `role_id` |  int |    -    | Paste a role\_id if the user shall be restored with another role than he had on deletion |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/users/restore/3', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 5,
    "username": "jeremy.doe",
    "first_name": "Jeremy",
    "last_name": "Doe",
    "active": true,
    "group_account": false,
    "role_id": 3,
    "profile_picture": null,
    "street": null,
    "zipcode": null,
    "city": null,
    "email": null,
    "phone": null,
    "birthdate": null,
    "gender": null,
    "entering_date": null,
    "leaving_date": null,
    "staff_number": null,
    "wants_email_notifications": false,
    "created_at": "2021-11-01 23:39:04",
    "updated_at": "2021-11-01 23:40:48",
    "deactivated_at": null,
    "deleted_at": null,
    "blacked_out_at": null,
    "default_route": null,
    "prevent_logout": false,
    "full_name": "Jeremy Doe"
  }
}
```

## Update

Update an existing `User` by `id`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/users/{id}`

**Request Keys**

| Key                         |   Type  | Description                                                                                       |
| --------------------------- | :-----: | ------------------------------------------------------------------------------------------------- |
| `username`                  |  string | The username of the `User` (min. 4 characters)                                                    |
| `password`                  |  string | The password for the `User` (min. 6 characters)                                                   |
| `first_name`                |  string | First name of this `User`                                                                         |
| `last_name`                 |  string | Last name of this `User`                                                                          |
| `active`                    | boolean | Whether the `User` is active                                                                      |
| `group_account`             | boolean | Whether the `User` is a Group Account                                                             |
| `role_id`                   | integer | Related [Role](/api-reference/roles.md)                                                           |
| `request_password_change`   | boolean | Whether the password should be changed by the `User` on the next login                            |
| `profile_picture`           |   file  | A filestream containing the profile picture                                                       |
| `street`                    |  string | Street where the `User` lives at                                                                  |
| `zipcode`                   |  string | Zipcode of the city the `User` lives in                                                           |
| `city`                      |  string | City where the `User` lives in                                                                    |
| `email`                     |  email  | Email of the `User`                                                                               |
| `phone`                     |  string | Phone number of the `User`                                                                        |
| `birthday`                  |   date  | Birthday of the `User`                                                                            |
| `gender`                    |  string | Gender of the `User` (`female` or `male`)                                                         |
| `entering_date`             |   date  | Date when the `User` enters/entered the company                                                   |
| `leaving_date`              |   date  | Date when the `User` leaves/left the company                                                      |
| `staff_number`              |  string | The identification number of the `User` inside a company                                          |
| `wants_email_notifications` | boolean | Whether the `User` get's notified about [Notifications](/api-reference/notifications.md) by email |

Keys with `*` are required.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/users/5', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'role_id' => '2'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 73,
    "username": "jeremy.doe",
    "first_name": "Jeremy",
    "last_name": "Doe",
    "active": true,
    "group_account": false,
    "role_id": 2,
    "profile_picture": null,
    "street": null,
    "zipcode": null,
    "city": null,
    "email": null,
    "phone": null,
    "birthdate": null,
    "gender": null,
    "entering_date": null,
    "leaving_date": null,
    "staff_number": null,
    "wants_email_notifications": false,
    "created_at": "2021-11-01 23:39:04",
    "updated_at": "2021-11-01 23:42:12",
    "deactivated_at": null,
    "deleted_at": null,
    "blacked_out_at": null,
    "default_route": null,
    "prevent_logout": false,
    "full_name": "Jeremy Doe"
  }
}
```

## Delete

Delete an existing `User` by `id`.

Deleted Users will be preserved so that they can be restored later on.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/users/{id}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/users/8', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
    "status": "success",
    "data": null
  }
}
```

## Blackout

Blackout a `User` by `id`.

To remove the personal information of the user while preserving the content he created - a user can be blacked out.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/users/blackout/{id}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/users/blackout/8', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 73,
    "username": "__73_1635806799",
    "first_name": "--",
    "last_name": "--",
    "active": false,
    "group_account": false,
    "role_id": 2,
    "profile_picture": null,
    "street": null,
    "zipcode": null,
    "city": null,
    "email": null,
    "phone": null,
    "birthdate": null,
    "gender": null,
    "entering_date": null,
    "leaving_date": null,
    "staff_number": null,
    "wants_email_notifications": false,
    "created_at": "2021-11-01 23:39:04",
    "updated_at": "2021-11-01 23:46:39",
    "deactivated_at": "2021-11-01 23:46:39",
    "deleted_at": "2021-11-01 23:43:41",
    "blacked_out_at": "2021-11-01 23:46:39",
    "default_route": null,
    "prevent_logout": false,
    "full_name": "-- --"
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.api.intratool.de/api-reference/users.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.