# Users

## Model Definition

**Alias**

`user`

**Relations**

| Relation                                                  | Key    | Type       | Relation Field(s) |
| --------------------------------------------------------- | ------ | ---------- | ----------------- |
| [Role](https://docs.api.intratool.de/api-reference/roles) | `role` | Belongs to | `role_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](https://docs.api.intratool.de/api-reference/roles)                                                           |
| `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](https://docs.api.intratool.de/api-reference/notifications) 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](https://docs.api.intratool.de/api-reference/roles)                                                           |
| `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](https://docs.api.intratool.de/api-reference/notifications) 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": "-- --"
  }
}
```