> For the complete documentation index, see [llms.txt](https://api-docs.intratool.help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.intratool.help/api-reference/contact-lists/contact-lists.md).

# ContactLists

## Introduction

`ContactLists` group [Contacts](/api-reference/contact-lists/contacts.md). Assignments to [Departments](/api-reference/departments.md) and [Users](/api-reference/users.md) restrict which lists appear in list results.

All endpoints require the [`contact-lists-show` permission](/api-reference/permissions.md#available-permissions).

## Model Definition

**Relations**

| Key           | Relation                                             | Type            | Relation Field(s)         |
| ------------- | ---------------------------------------------------- | --------------- | ------------------------- |
| `user`        | [User](/api-reference/users.md)                      | Belongs to      | `user_id`                 |
| `contacts`    | [Contacts](/api-reference/contact-lists/contacts.md) | Has many        | `contact_list_id`         |
| `departments` | [Departments](/api-reference/departments.md)         | Belongs to many | `department_contact_list` |
| `users`       | [Users](/api-reference/users.md)                     | Belongs to many | `user_contact_list`       |

These relations are included by default. Pass an empty `relations` value to suppress them.

**Search Types**

* `contact-lists` - Filters lists by `name`.
* `contacts` - Filters the included `contacts` relation by contact data without removing top-level lists.

**Order Directions**

* `asc` - Sorts values in ascending order.
* `desc` - Sorts values in descending order.

Uppercase `ASC` and `DESC` are also accepted.

## List

List visible `ContactLists`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/contact-lists`

**Request Keys**

| Key               | Type      | Default           | Description                                                             |
| ----------------- | --------- | ----------------- | ----------------------------------------------------------------------- |
| `selects`         | `string`  | All fields        | Comma-separated fields to return.                                       |
| `relations`       | `string`  | Default relations | Pipe-separated [relations](#relations); an empty value suppresses them. |
| `search_text`     | `string`  | -                 | Text used by the selected search behavior.                              |
| `search_type`     | `string`  | `contact-lists`   | [Search type](#search-types).                                           |
| `limit`           | `integer` | No limit          | Maximum number of lists. Minimum `1`.                                   |
| `order_field`     | `string`  | `name`            | Field used for ordering.                                                |
| `order_direction` | `string`  | `asc`             | [Order direction](#order-directions).                                   |

**Behavior**

* Users with `contact-lists-administration-rights` receive every non-deleted list except lists created by the reserved intratool Admin account.
* Other users receive lists they created themselves. For other lists, each configured department and user restriction must match; an unconfigured restriction does not limit visibility.
* `search_type=contacts` affects the included `contacts` relation only. Include that relation to receive the matching contacts.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/contact-lists', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => [
        'relations' => '',
        'limit' => 2,
        'order_field' => 'sort_number',
        'order_direction' => 'asc'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 1,
    "user_id": 3,
    "name": "Emergency Contacts",
    "sort_number": 1,
    "created_at": "2026-08-01 09:00:00",
    "updated_at": "2026-08-01 09:00:00",
    "deleted_at": null
  },
  {
    "id": 2,
    "user_id": 4,
    "name": "Business Partners",
    "sort_number": 2,
    "created_at": "2026-08-02 10:30:00",
    "updated_at": "2026-08-05 14:15:00",
    "deleted_at": null
  }
]
```

## Show

Show one `ContactList`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description      |
| --------- | --------- | ---------------- |
| `id`      | `integer` | Contact list ID. |

**Request Keys**

| Key         | Type     | Default           | Description                                                             |
| ----------- | -------- | ----------------- | ----------------------------------------------------------------------- |
| `selects`   | `string` | All fields        | Comma-separated fields to return.                                       |
| `relations` | `string` | Default relations | Pipe-separated [relations](#relations); an empty value suppresses them. |

**Behavior**

The endpoint resolves the ID independently of the department and user assignment filters applied by List.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 1,
  "user_id": 3,
  "name": "Emergency Contacts",
  "sort_number": 1,
  "created_at": "2026-08-01 09:00:00",
  "updated_at": "2026-08-01 09:00:00",
  "deleted_at": null
}
```

## Create

Create a new `ContactList`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/contact-lists`

**Request Keys**

| Key              | Type               | Default     | Description                                               |
| ---------------- | ------------------ | ----------- | --------------------------------------------------------- |
| `name`\*         | `string`           | -           | Unique list name.                                         |
| `sort_number`    | `integer`          | End of list | Requested list position.                                  |
| `department_ids` | `string` \| `null` | `null`      | Comma-separated department IDs that may receive the list. |
| `user_ids`       | `string` \| `null` | `null`      | Comma-separated user IDs that may receive the list.       |

Keys with `*` are required.

**Behavior**

* Requires `contact-lists-create-contact-lists` or `contact-lists-administration-rights`.
* The authenticated user is stored as `user_id`.
* `sort_number` is normalized into the existing sequence. Omission appends the list.
* Department and user IDs are attached after creation. Empty assignment values are normalized to no assignments.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/contact-lists', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Service Providers',
        'department_ids' => '1,2',
        'user_ids' => '4,5'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "user_id": 3,
    "name": "Service Providers",
    "sort_number": 3,
    "created_at": "2026-08-07 11:00:00",
    "updated_at": "2026-08-07 11:00:00"
  }
}
```

## Update

Update an existing `ContactList`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description      |
| --------- | --------- | ---------------- |
| `id`      | `integer` | Contact list ID. |

**Request Keys**

| Key              | Type               | Description                                                        |
| ---------------- | ------------------ | ------------------------------------------------------------------ |
| `name`           | `string`           | Unique list name.                                                  |
| `sort_number`    | `integer`          | Requested list position.                                           |
| `department_ids` | `string` \| `null` | Comma-separated department IDs; an empty value clears assignments. |
| `user_ids`       | `string` \| `null` | Comma-separated user IDs; an empty value clears assignments.       |

**Behavior**

* Requires `contact-lists-edit-all-contact-lists`, or ownership together with `contact-lists-edit-own-contact-lists`. Administration rights satisfy either check.
* Changing `sort_number` reorders the remaining lists.
* Omitted assignment keys preserve their current values; provided values replace the complete affected assignment set.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/contact-lists/3', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Approved Service Providers',
        'sort_number' => 1,
        'department_ids' => '2',
        'user_ids' => null
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "user_id": 3,
    "name": "Approved Service Providers",
    "sort_number": 1,
    "created_at": "2026-08-07 11:00:00",
    "updated_at": "2026-08-07 11:15:00",
    "deleted_at": null
  }
}
```

## Delete

Delete an existing `ContactList`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description      |
| --------- | --------- | ---------------- |
| `id`      | `integer` | Contact list ID. |

**Behavior**

* Requires `contact-lists-delete-all-contact-lists`, or ownership together with `contact-lists-delete-own-contact-lists`. Administration rights satisfy either check.
* The list and all contained contacts are soft-deleted. Remaining lists are reordered.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": []
}
```