ContactLists

Introduction

ContactLists group Contacts. Assignments to Departments and Users restrict which lists appear in list results.

All endpoints require the contact-lists-show permission.

Model Definition

Relations

Key	Relation	Type	Relation Field(s)
user	User	Belongs to	user_id
contacts	Contacts	Has many	contact_list_id
departments	Departments	Belongs to many	department_contact_list
users	Users	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

GET /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; an empty value suppresses them.
search_text	string	-	Text used by the selected search behavior.
search_type	string	contact-lists	Search type.
limit	integer	No limit	Maximum number of lists. Minimum 1.
order_field	string	name	Field used for ordering.
order_direction	string	asc	Order direction.

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

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'
    ]
]);

Example Response

[
  {
    "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

GET /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; an empty value suppresses them.

Behavior

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

Example Request

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' => '']
]);

Example Response

{
  "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

POST /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

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'
    ]
]);

Example Response

{
  "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

PUT /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

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
    ]
]);

Example Response

{
  "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

DELETE /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

PHP

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

Example Response

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