# Team

A teammate is a special user who represents a Tiledesk user invited to a project with a specific role. When you work with teammates very often you will not use the user\_id of the Tiledesk user but rather the specific id of your teammate in the project. In the Tiledesk API the temamate is named project\_user. For example, if you want to know your project\_user in a specific project, all you have to do is call this API: [Get a teammate by id](#get-a-teammate-by-id).

## The Team Model

| Key                        | Type    | Description                                                                                                |
| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| id                         | String  | The unique identifier for the teammate which is given by Tiledesk.                                         |
| role                       | String  | The teammate role. Values: owner, agent, admin, user, guest                                                |
| user\_available            | Boolean | Dermine if the teammate is available or unavailable to accept requests                                     |
| id\_user                   | Object  | The user object referenced by the teammate                                                                 |
| max\_served\_chat          | Number  | Number of chats that agent is allowed to take at one time (Only Enterprise)                                |
| number\_assigned\_requests | Number  | Number of active request for the teammate (Only Enterprise)                                                |
| status                     | String  | The status of a teammate. Can be "active" or "disabled"                                                    |
| isBusy                     | Boolean | Determine if the teammate is busy (Only Enterprise)                                                        |
| profileStatus              | String  | It is an alias associated to the teammate availability. For example: inactive, to the toilet, on the phone |
| attributes                 | Object  | The custom attributes which are set for the teammate.                                                      |
| tags                       | Array   | A list of tags objects associated with the teammate.                                                       |
| settings                   | Object  | The setting configurations of the teammate.                                                                |
| presence                   | Object  | The presence info of the teammate.                                                                         |
| isAuthenticated            | Boolean | Returns true if is strongly authenticated (custom-auth or email/password), false otherwise (anonymous).    |
| isBusy                     | Boolean | Returns true if is teammate is busy, false otherwise. See Tiledesk Smart Assignment for more info.         |
| createdAt                  | String  | The time (ISO-8601 date string) when the teammate was created.                                             |
| updatedAt                  | String  | The time (ISO-8601 date string) when the teammate was updated.                                             |
| createdBy                  | String  | The unique identifier of the row creator                                                                   |
| id\_project                | String  | The unique identifier of the project                                                                       |
| trashed                    | Boolean | True if the teammate has been removed from the project                                                     |

### The Presence model

Presence lets you track the online and offline status of the teammates in real-time (if you use Tiledesk [Websocket](/apis/realtime-api.md) or [Webhook](/apis/webhooks.md)) and store the information state. Possible values: online, offline. Attention: an agent passes from online to offline only when he closed all Tiledesk messaging apps (eg Agent web chat in all tabs and mobile apps).

### Agent availability

The field **user\_available** determines if the teammate is available or unavailable to accept requests. Attention: Agent availability changes only when the agent explicitly changes from the UI from available to unavailable. If an agent is available and logs out, the agent remains available as he may have decided to serve chats from another channel (eg. Tiledesk mobile app).

## Get the team

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/project_users`

Return the team members and availability. Use the optional query parameter `trashed=true` to include trashed teammates in the response.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | the Project Id is a unique code assigned to your project when you create it in Tiledesk. |

#### Query Parameters

| Name    | Type   | Description                                                                                                                              |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| trashed | string | Optional. Set to `true` to include trashed teammates in the response. When `false` or omitted, trashed teammates are excluded (default). |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |

{% tabs %}
{% tab title="200 List of teammates. Without trashed (default): only active." %}

```
[
   {
      "_id":"5df2240cecd41b00173a06bc",
      "id_project":"5df2240cecd41b00173a06bb",
      "id_user":{
         "_id":"5aaa99024c3b110014b478f0",
         "email":"andrea.leo@frontiere21.it",
         "firstname":"Andrea",
         "lastname":"Leo",
         "emailverified":true,
         "__v":0,
         "resetpswrequestid":""
      },
      "role":"owner",
      "user_available":true,
      "trashed":false,
      "createdBy":"5aaa99024c3b110014b478f0",
      "createdAt":"2019-12-12T11:27:08.581Z",
      "updatedAt":"2019-12-12T11:27:08.581Z",
      "__v":0
   },
   {
      "_id":"5df34ab80bc923001792e274",
      "id_project":"5df2240cecd41b00173a06bb",
      "id_user":{
         "_id":"5de9200d6722370017731969",
         "email":"nuovopre@f21test.it",
         "firstname":"Nuovopre",
         "lastname":"Pre",
         "emailverified":false,
         "createdAt":"2019-12-05T15:19:41.296Z",
         "updatedAt":"2019-12-05T15:19:41.296Z",
         "__v":0
      },
      "role":"admin",
      "user_available":true,
      "trashed":false,
      "createdBy":"5aaa99024c3b110014b478f0",
      "createdAt":"2019-12-13T08:24:24.586Z",
      "updatedAt":"2020-01-04T09:45:26.331Z",
      "__v":0
   }
]
```

{% endtab %}
{% endtabs %}

Example (default, exclude trashed):

```
curl -v -X GET \
  -u user@example.com:password \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users
```

Example (include trashed teammates):

```
curl -v -X GET \
  -u user@example.com:password \
  "https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users?trashed=true"
```

## Get a teammate by id

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/project_users/:project_user_id`

#### Path Parameters

| Name              | Type   | Description                                                                              |
| ----------------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id       | string | the Project Id is a unique code assigned to your project when you create it in Tiledesk. |
| project\_user\_id | string | The teammate identifier.                                                                 |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |

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

```
   {
      "_id":"5df2240cecd41b00173a06bc",
      "id_project":"5df2240cecd41b00173a06bb",
      "id_user":{
         "_id":"5aaa99024c3b110014b478f0",
         "email":"andrea.leo@frontiere21.it",
         "firstname":"Andrea",
         "lastname":"Leo",
         "emailverified":true,
         "__v":0,
         "resetpswrequestid":""
      },
      "role":"owner",
      "user_available":true,
      "createdBy":"5aaa99024c3b110014b478f0",
      "createdAt":"2019-12-12T11:27:08.581Z",
      "updatedAt":"2019-12-12T11:27:08.581Z",
      "__v":0
   }
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X GET \
  -u user@example.com:password \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df2240cecd41b00173a06bc
```

## Get a teammate by user id

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/project_users/users/:user_id`

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | the Project Id is a unique code assigned to your project when you create it in Tiledesk. |
| user\_id    | string | The user identifier.                                                                     |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |

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

```
   {
      "_id":"5df2240cecd41b00173a06bc",
      "id_project":"5df2240cecd41b00173a06bb",
      "id_user":{
         "_id":"5aaa99024c3b110014b478f0",
         "email":"andrea.leo@frontiere21.it",
         "firstname":"Andrea",
         "lastname":"Leo",
         "emailverified":true,
         "__v":0,
         "resetpswrequestid":""
      },
      "role":"owner",
      "user_available":true,
      "createdBy":"5aaa99024c3b110014b478f0",
      "createdAt":"2019-12-12T11:27:08.581Z",
      "updatedAt":"2019-12-12T11:27:08.581Z",
      "__v":0
   }
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X GET \
  -u user@example.com:password \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/users/5aaa99024c3b110014b478f0
```

## Invite an agent

<mark style="color:green;">`POST`</mark> `https://api.tiledesk.com/v3/:project_id/project_users/invite`

Invite an agent to a project.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: admin |
| Content-Type  | string | use "application/json" value                                |

#### Request Body

| Name            | Type    | Description                                                        |
| --------------- | ------- | ------------------------------------------------------------------ |
| email           | string  | the agent email address                                            |
| role            | string  | the agent role. Accepted values: agent, admin                      |
| firstname       | string  | the firstname of the agent                                         |
| lastname        | string  | the lastname of the agent                                          |
| user\_available | boolean | the initial agent status. Available (true) or unavailable (false). |

{% tabs %}
{% tab title="200 Teammate invited successfully" %}

```
{
  "_id": "5df34ab80bc923001792e274",
  "id_project": "5df2240cecd41b00173a06bb",
  "id_user": {
    "_id": "5de9200d6722370017731969",
    "email": "nuovopre@f21test.it",
    "firstname": "Nuovopre",
    "lastname": "Pre",
    "emailverified": false,
    "createdAt": "2019-12-05T15:19:41.296Z",
    "updatedAt": "2019-12-05T15:19:41.296Z",
    "__v": 0
  },
  "role": "admin",
  "user_available": true,
  "createdBy": "5aaa99024c3b110014b478f0",
  "createdAt": "2019-12-13T08:24:24.586Z",
  "updatedAt": "2019-12-13T08:24:24.586Z",
  "__v": 0
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X POST \
  -H 'Content-Type: application/json' \
  -u user@example.com:password \
  -d '{"email":"agent@example.com","role":"agent","firstname":"Mario","lastname":"Rossi","user_available":true}' \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/invite
```

## Update the current logged teammate

<mark style="color:orange;">`PUT`</mark> `https://api.tiledesk.com/v3/:project_id/project_users/`

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |
| Content-Type  | string | use "application/json" value                                |

#### Request Body

| Name              | Type    | Description                                                                                                 |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| role              | string  | The teammate role. Permitted values: admin, agent.                                                          |
| user\_available   | boolean | <p>The teammate availability. True for available, false for unavailable.</p><p><em>Default is true</em></p> |
| max\_served\_chat | number  | The number of concurrent chats the teammate can take at once.                                               |
| attributes        | object  | The teammate custom attributes                                                                              |
| settings          | object  | The teammate settings object                                                                                |

{% tabs %}
{% tab title="200 Updated teammate" %}

```
{
  "_id": "5df2240cecd41b00173a06bc",
  "id_project": "5df2240cecd41b00173a06bb",
  "id_user": {
    "_id": "5aaa99024c3b110014b478f0",
    "email": "andrea.leo@frontiere21.it",
    "firstname": "Andrea",
    "lastname": "Leo",
    "emailverified": true,
    "__v": 0,
    "resetpswrequestid": ""
  },
  "role": "admin",
  "user_available": false,
  "createdBy": "5aaa99024c3b110014b478f0",
  "createdAt": "2019-12-12T11:27:08.581Z",
  "updatedAt": "2020-01-04T09:50:00.000Z",
  "__v": 0
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X PUT \
  -H 'Content-Type: application/json' \
  -u user@example.com:password \
  -d '{"user_available":false,"role":"admin"}' \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/
```

## Update a teammate by id

<mark style="color:orange;">`PUT`</mark> `https://api.tiledesk.com/v3/:project_id/project_users/:project_user_id`

It requires admin role

#### Path Parameters

| Name              | Type   | Description                                                                              |
| ----------------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id       | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| project\_user\_id | string | The teammate identifier.                                                                 |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: admin |
| Content-Type  | string | use "application/json" value                                |

#### Request Body

| Name              | Type    | Description                                                                                                 |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| role              | string  | The teammate role. Permitted values: admin, agent.                                                          |
| user\_available   | boolean | <p>The teammate availability. True for available, false for unavailable.</p><p><em>Default is true</em></p> |
| max\_served\_chat | number  | The number of concurrent chats the teammate can take at once.                                               |
| attributes        | object  | The teammate custom attributes                                                                              |
| settings          | object  | The teammate settings object                                                                                |

{% tabs %}
{% tab title="200 Updated teammate" %}

```
{
  "_id": "5df34ab80bc923001792e274",
  "id_project": "5df2240cecd41b00173a06bb",
  "id_user": {
    "_id": "5de9200d6722370017731969",
    "email": "nuovopre@f21test.it",
    "firstname": "Nuovopre",
    "lastname": "Pre",
    "emailverified": false,
    "createdAt": "2019-12-05T15:19:41.296Z",
    "updatedAt": "2019-12-05T15:19:41.296Z",
    "__v": 0
  },
  "role": "agent",
  "user_available": true,
  "createdBy": "5aaa99024c3b110014b478f0",
  "createdAt": "2019-12-13T08:24:24.586Z",
  "updatedAt": "2020-01-04T09:55:00.000Z",
  "__v": 0
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X PUT \
  -H 'Content-Type: application/json' \
  -u user@example.com:password \
  -d '{"role":"agent","user_available":true}' \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df34ab80bc923001792e274
```

## Remove a teammate from the project

<mark style="color:red;">`DELETE`</mark> `https://api.tiledesk.com/v3/:project_id/project_users/:project_user_id`

Remove an agent from a project. The type of removal is controlled by query parameters:

* **soft** (`soft=true`): Soft delete (ghost delete). The teammate is marked as trashed and can be restored later. Data is preserved.
* **hard** (`hard=true`): Hard delete. The teammate is permanently removed from the database. **Warning:** statistics referring to this teammate will be lost.
* **Disable** (no `soft` or `hard`): The teammate is disabled but remains visible on the dashboard and can be re-enabled. Sets `status: "disabled"` and `user_available: false`.

#### Path Parameters

| Name              | Type   | Description                                                                              |
| ----------------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id       | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| project\_user\_id | string | The teammate identifier.                                                                 |

#### Query Parameters

| Name | Type   | Description                                                                                                                            |
| ---- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| soft | string | Set to `true` for soft delete (ghost delete). The teammate is marked as trashed and can be restored.                                   |
| hard | string | Set to `true` for hard delete. Permanently removes the teammate from the database; statistics referring to this teammate will be lost. |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: admin |

{% tabs %}
{% tab title="200 Returns the updated or removed project\_user. For soft delete: trashed is true; for disable: status is "disabled" and user\_available is false; for hard delete: the deleted project\_user object." %}

```
{
  "_id": "5df34ab80bc923001792e274",
  "id_project": "5df2240cecd41b00173a06bb",
  "id_user": {
    "_id": "5de9200d6722370017731969",
    "firstname": "Nuovopre",
    "lastname": "Pre"
  },
  "role": "admin",
  "user_available": false,
  "status": "disabled",
  "trashed": false,
  "createdBy": "5aaa99024c3b110014b478f0",
  "createdAt": "2019-12-13T08:24:24.586Z",
  "updatedAt": "2020-01-04T10:00:00.000Z",
  "__v": 0
}
```

{% endtab %}

{% tab title="404 Project user not found" %}

```
{
  "success": false,
  "error": "Project user not found with id 5df34ab80bc923001792e274"
}
```

{% endtab %}

{% tab title="500 Server error" %}

```
{
  "success": false,
  "msg": "Error deleting Project User with id ..."
}
```

{% endtab %}
{% endtabs %}

Example (soft delete - can be restored):

```
curl -v -X DELETE \
  -u user@example.com:password \
  "https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df34ab80bc923001792e274?soft=true"
```

Example (hard delete - permanent, statistics lost):

```
curl -v -X DELETE \
  -u user@example.com:password \
  "https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df34ab80bc923001792e274?hard=true"
```

Example (disable - remains visible, can be re-enabled):

```
curl -v -X DELETE \
  -u user@example.com:password \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df34ab80bc923001792e274
```

## Restore a trashed teammate

<mark style="color:orange;">`PUT`</mark> `https://api.tiledesk.com/v3/:project_id/project_users/:project_user_id/restore`

Restore a teammate that was previously soft-deleted (trashed). Sets `trashed: false` and `status: "active"`. The teammate must be in trashed state; if not, the API returns 400.

#### Path Parameters

| Name              | Type   | Description                                                                              |
| ----------------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id       | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| project\_user\_id | string | The teammate identifier (project\_user id) to restore.                                   |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minimum role: admin |

{% tabs %}
{% tab title="200 Teammate restored successfully" %}

```
{
  "_id": "5df34ab80bc923001792e274",
  "id_project": "5df2240cecd41b00173a06bb",
  "id_user": {
    "_id": "5de9200d6722370017731969",
    "email": "nuovopre@f21test.it",
    "firstname": "Nuovopre",
    "lastname": "Pre",
    "emailverified": false,
    "createdAt": "2019-12-05T15:19:41.296Z",
    "updatedAt": "2019-12-05T15:19:41.296Z",
    "__v": 0
  },
  "role": "admin",
  "user_available": true,
  "status": "active",
  "trashed": false,
  "createdBy": "5aaa99024c3b110014b478f0",
  "createdAt": "2019-12-13T08:24:24.586Z",
  "updatedAt": "2020-01-04T10:05:00.000Z",
  "__v": 0
}
```

{% endtab %}

{% tab title="400 Teammate is not trashed and cannot be restored" %}

```
{
  "success": false,
  "error": "Project user is not trashed, cannot restore"
}
```

{% endtab %}

{% tab title="404 Teammate not found" %}

```
{
  "success": false,
  "error": "Project user not found with id ..."
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X PUT \
  -u user@example.com:password \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df34ab80bc923001792e274/restore
```


---

# 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://developer.tiledesk.com/apis/rest-api/team.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.