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

# Contacts

## Introduction

`Contacts` store organization and contact-person details within a [ContactList](/api-reference/contact-lists/contact-lists.md).

The `notes` field uses the shared [Rich Text](/introduction/rich-text.md) HTML format. 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`         |
| `contactList` | [ContactList](/api-reference/contact-lists/contact-lists.md) | Belongs to | `contact_list_id` |

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

**Search Fields**

* `name` - Contact name.
* `phone` - General phone number.
* `fax` - Fax number.
* `email` - General email address.
* `street` - Street address.
* `zipcode` - Postal code.
* `city` - City.
* `notes` - Notes content.
* `contact_person_name` - Contact person's name.
* `contact_person_position` - Contact person's position.
* `contact_person_phone` - Contact person's phone number.
* `contact_person_mobile_phone` - Contact person's mobile phone number.
* `contact_person_email` - Contact person's email address.

**Order Directions**

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

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

**CSV Columns**

* `contact_list` - Contact list name resolved to `contact_list_id`.
* `name` - Contact name.
* `phone` - General phone number.
* `fax` - Fax number.
* `email` - General email address.
* `street` - Street address.
* `zipcode` - Postal code.
* `city` - City.
* `notes` - Notes content.
* `contact_person_name` - Contact person's name.
* `contact_person_position` - Contact person's position.
* `contact_person_phone` - Contact person's phone number.
* `contact_person_mobile_phone` - Contact person's mobile phone number.
* `contact_person_email` - Contact person's email address.

## List

List `Contacts`.

**Definition**

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

**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 to filter the selected field.                                 |
| `search_type`     | `string`  | `name`            | [Contact field](#search-fields) to search.                              |
| `limit`           | `integer` | No limit          | Maximum number of contacts. Minimum `1`.                                |
| `order_field`     | `string`  | `name`            | Field used for ordering.                                                |
| `order_direction` | `string`  | `asc`             | [Order direction](#order-directions).                                   |

**Behavior**

Contact-list department and user assignments do not restrict this endpoint. Contacts created by the reserved intratool Admin account are omitted.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 1,
    "user_id": 3,
    "contact_list_id": 1,
    "name": "Example Logistics Ltd.",
    "phone": "+44 20 7946 0100",
    "fax": "+44 20 7946 0101",
    "email": "office@example.com",
    "street": "1 Example Road",
    "zipcode": "SW1A 1AA",
    "city": "London",
    "notes": "<p>Available around the clock for urgent deliveries.</p>",
    "contact_person_name": "Ada Lovelace",
    "contact_person_position": "Operations Manager",
    "contact_person_phone": "+44 20 7946 0110",
    "contact_person_mobile_phone": "+44 7700 900100",
    "contact_person_email": "ada@example.com",
    "created_at": "2026-08-01 09:00:00",
    "updated_at": "2026-08-05 14:15:00",
    "deleted_at": null
  },
  {
    "id": 2,
    "user_id": 4,
    "contact_list_id": 2,
    "name": "Northside Clinic",
    "phone": "+1 202 555 0142",
    "fax": null,
    "email": "reception@example.org",
    "street": null,
    "zipcode": null,
    "city": "Washington",
    "notes": null,
    "contact_person_name": null,
    "contact_person_position": null,
    "contact_person_phone": null,
    "contact_person_mobile_phone": null,
    "contact_person_email": null,
    "created_at": "2026-08-02 10:30:00",
    "updated_at": "2026-08-02 10:30:00",
    "deleted_at": null
  }
]
```

## Show

Show one `Contact`.

**Definition**

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

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `id`      | `integer` | Contact 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**

Contact-list department and user assignments do not restrict this endpoint.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 1,
  "user_id": 3,
  "contact_list_id": 1,
  "name": "Example Logistics Ltd.",
  "phone": "+44 20 7946 0100",
  "fax": "+44 20 7946 0101",
  "email": "office@example.com",
  "street": "1 Example Road",
  "zipcode": "SW1A 1AA",
  "city": "London",
  "notes": "<p>Available around the clock for urgent deliveries.</p>",
  "contact_person_name": "Ada Lovelace",
  "contact_person_position": "Operations Manager",
  "contact_person_phone": "+44 20 7946 0110",
  "contact_person_mobile_phone": "+44 7700 900100",
  "contact_person_email": "ada@example.com",
  "created_at": "2026-08-01 09:00:00",
  "updated_at": "2026-08-05 14:15:00",
  "deleted_at": null
}
```

## Create

Create a new `Contact`.

**Definition**

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

**Request Keys**

| Key                           | Type               | Default | Description                                                             |
| ----------------------------- | ------------------ | ------- | ----------------------------------------------------------------------- |
| `contact_list_id`\*           | `integer`          | -       | Parent [ContactList](/api-reference/contact-lists/contact-lists.md) ID. |
| `name`\*                      | `string`           | -       | Contact name.                                                           |
| `phone`                       | `string` \| `null` | `null`  | General phone number.                                                   |
| `fax`                         | `string` \| `null` | `null`  | Fax number.                                                             |
| `email`                       | `string` \| `null` | `null`  | Valid general email address.                                            |
| `street`                      | `string` \| `null` | `null`  | Street address.                                                         |
| `zipcode`                     | `string` \| `null` | `null`  | Postal code.                                                            |
| `city`                        | `string` \| `null` | `null`  | City.                                                                   |
| `notes`                       | `string` \| `null` | `null`  | Notes in [Rich Text](/introduction/rich-text.md) HTML.                  |
| `contact_person_name`         | `string` \| `null` | `null`  | Contact person's name.                                                  |
| `contact_person_position`     | `string` \| `null` | `null`  | Contact person's position.                                              |
| `contact_person_phone`        | `string` \| `null` | `null`  | Contact person's phone number.                                          |
| `contact_person_mobile_phone` | `string` \| `null` | `null`  | Contact person's mobile phone number.                                   |
| `contact_person_email`        | `string` \| `null` | `null`  | Contact person's email address.                                         |

Keys with `*` are required.

**Behavior**

* Requires `contact-lists-create-contacts` or `contact-lists-administration-rights`.
* The authenticated user is stored as `user_id`.
* Empty optional contact values are normalized to `null`.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/contacts', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'contact_list_id' => 1,
        'name' => 'Example Engineering Inc.',
        'phone' => '+1 202 555 0168',
        'fax' => null,
        'email' => 'office@example.net',
        'street' => '100 Example Avenue',
        'zipcode' => '20001',
        'city' => 'Washington',
        'notes' => '<p>Preferred supplier for replacement components.</p>',
        'contact_person_name' => 'Grace Hopper',
        'contact_person_position' => 'Technical Director',
        'contact_person_phone' => '+1 202 555 0170',
        'contact_person_mobile_phone' => '+1 202 555 0171',
        'contact_person_email' => 'grace@example.net'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "user_id": 3,
    "contact_list_id": 1,
    "name": "Example Engineering Inc.",
    "phone": "+1 202 555 0168",
    "fax": null,
    "email": "office@example.net",
    "street": "100 Example Avenue",
    "zipcode": "20001",
    "city": "Washington",
    "notes": "<p>Preferred supplier for replacement components.</p>",
    "contact_person_name": "Grace Hopper",
    "contact_person_position": "Technical Director",
    "contact_person_phone": "+1 202 555 0170",
    "contact_person_mobile_phone": "+1 202 555 0171",
    "contact_person_email": "grace@example.net",
    "created_at": "2026-08-07 11:00:00",
    "updated_at": "2026-08-07 11:00:00"
  }
}
```

## Update

Update an existing `Contact`.

**Definition**

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

**Route Parameters**

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

**Request Keys**

| Key                           | Type               | Description                                                             |
| ----------------------------- | ------------------ | ----------------------------------------------------------------------- |
| `contact_list_id`             | `integer`          | Parent [ContactList](/api-reference/contact-lists/contact-lists.md) ID. |
| `name`                        | `string`           | Contact name.                                                           |
| `phone`                       | `string` \| `null` | General phone number.                                                   |
| `fax`                         | `string` \| `null` | Fax number.                                                             |
| `email`                       | `string` \| `null` | Valid general email address.                                            |
| `street`                      | `string` \| `null` | Street address.                                                         |
| `zipcode`                     | `string` \| `null` | Postal code.                                                            |
| `city`                        | `string` \| `null` | City.                                                                   |
| `notes`                       | `string` \| `null` | Notes in [Rich Text](/introduction/rich-text.md) HTML.                  |
| `contact_person_name`         | `string` \| `null` | Contact person's name.                                                  |
| `contact_person_position`     | `string` \| `null` | Contact person's position.                                              |
| `contact_person_phone`        | `string` \| `null` | Contact person's phone number.                                          |
| `contact_person_mobile_phone` | `string` \| `null` | Contact person's mobile phone number.                                   |
| `contact_person_email`        | `string` \| `null` | Contact person's email address.                                         |

**Behavior**

* Requires `contact-lists-edit-all-contacts`, or ownership together with `contact-lists-edit-own-contacts`. Administration rights satisfy either check.
* Empty optional contact values are normalized to `null`.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/contacts/3', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'phone' => '+1 202 555 0180',
        'notes' => '<p>Preferred supplier. Use the updated service number for urgent requests.</p>',
        'contact_person_mobile_phone' => null
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 3,
    "user_id": 3,
    "contact_list_id": 1,
    "name": "Example Engineering Inc.",
    "phone": "+1 202 555 0180",
    "fax": null,
    "email": "office@example.net",
    "street": "100 Example Avenue",
    "zipcode": "20001",
    "city": "Washington",
    "notes": "<p>Preferred supplier. Use the updated service number for urgent requests.</p>",
    "contact_person_name": "Grace Hopper",
    "contact_person_position": "Technical Director",
    "contact_person_phone": "+1 202 555 0170",
    "contact_person_mobile_phone": null,
    "contact_person_email": "grace@example.net",
    "created_at": "2026-08-07 11:00:00",
    "updated_at": "2026-08-07 11:15:00",
    "deleted_at": null
  }
}
```

## Delete

Delete an existing `Contact`.

**Definition**

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

**Route Parameters**

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

**Behavior**

* Requires `contact-lists-delete-all-contacts`, or ownership together with `contact-lists-delete-own-contacts`. Administration rights satisfy either check.
* The contact is soft-deleted.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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

## Download Import Template

Download a CSV template containing the supported contact columns.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/contacts/import-template`

**Request Keys**

| Key                           | Type     | Default                       | Description                                                    |
| ----------------------------- | -------- | ----------------------------- | -------------------------------------------------------------- |
| `contact_list`                | `string` | `contact_list`                | Header name for the `contact_list` [CSV column](#csv-columns). |
| `name`                        | `string` | `name`                        | Header name for the `name` CSV column.                         |
| `phone`                       | `string` | `phone`                       | Header name for the `phone` CSV column.                        |
| `fax`                         | `string` | `fax`                         | Header name for the `fax` CSV column.                          |
| `email`                       | `string` | `email`                       | Header name for the `email` CSV column.                        |
| `street`                      | `string` | `street`                      | Header name for the `street` CSV column.                       |
| `zipcode`                     | `string` | `zipcode`                     | Header name for the `zipcode` CSV column.                      |
| `city`                        | `string` | `city`                        | Header name for the `city` CSV column.                         |
| `notes`                       | `string` | `notes`                       | Header name for the `notes` CSV column.                        |
| `contact_person_name`         | `string` | `contact_person_name`         | Header name for the `contact_person_name` CSV column.          |
| `contact_person_position`     | `string` | `contact_person_position`     | Header name for the `contact_person_position` CSV column.      |
| `contact_person_phone`        | `string` | `contact_person_phone`        | Header name for the `contact_person_phone` CSV column.         |
| `contact_person_mobile_phone` | `string` | `contact_person_mobile_phone` | Header name for the `contact_person_mobile_phone` CSV column.  |
| `contact_person_email`        | `string` | `contact_person_email`        | Header name for the `contact_person_email` CSV column.         |

**Behavior**

* This compatibility endpoint uses application-session authentication instead of the API bearer-token guard.
* The response downloads `intratool-kontaktdaten-vorlage.csv` with one header row. Provided request values replace the matching default column names.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/contacts/import-template', [
    'headers' => ['Cookie' => '{sessionCookie}'],
    'query' => [
        'contact_list' => 'list',
        'name' => 'full_name',
        'email' => 'email_address'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```http
HTTP/1.1 200 OK
Content-Disposition: attachment; filename=intratool-kontaktdaten-vorlage.csv

list,full_name,phone,fax,email_address,street,zipcode,city,notes,contact_person_name,contact_person_position,contact_person_phone,contact_person_mobile_phone,contact_person_email
```

## Parse CSV

Parse an uploaded contacts CSV file into proposed create, update, and delete operations.

**Definition**

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

**Request Keys**

| Key                           | Type      | Default                       | Description                                                                 |
| ----------------------------- | --------- | ----------------------------- | --------------------------------------------------------------------------- |
| `contact_data_csv`\*          | `file`    | -                             | CSV or plain-text file with a header row.                                   |
| `update_contacts`             | `boolean` | `false`                       | Include matching contacts in `update_contacts`.                             |
| `delete_contacts`             | `boolean` | `false`                       | Include contacts whose names are absent from the file in `delete_contacts`. |
| `contact_list`                | `string`  | `contact_list`                | Header mapped to the `contact_list` [CSV column](#csv-columns).             |
| `name`                        | `string`  | `name`                        | Header mapped to the `name` CSV column.                                     |
| `phone`                       | `string`  | `phone`                       | Header mapped to the `phone` CSV column.                                    |
| `fax`                         | `string`  | `fax`                         | Header mapped to the `fax` CSV column.                                      |
| `email`                       | `string`  | `email`                       | Header mapped to the `email` CSV column.                                    |
| `street`                      | `string`  | `street`                      | Header mapped to the `street` CSV column.                                   |
| `zipcode`                     | `string`  | `zipcode`                     | Header mapped to the `zipcode` CSV column.                                  |
| `city`                        | `string`  | `city`                        | Header mapped to the `city` CSV column.                                     |
| `notes`                       | `string`  | `notes`                       | Header mapped to the `notes` CSV column.                                    |
| `contact_person_name`         | `string`  | `contact_person_name`         | Header mapped to the `contact_person_name` CSV column.                      |
| `contact_person_position`     | `string`  | `contact_person_position`     | Header mapped to the `contact_person_position` CSV column.                  |
| `contact_person_phone`        | `string`  | `contact_person_phone`        | Header mapped to the `contact_person_phone` CSV column.                     |
| `contact_person_mobile_phone` | `string`  | `contact_person_mobile_phone` | Header mapped to the `contact_person_mobile_phone` CSV column.              |
| `contact_person_email`        | `string`  | `contact_person_email`        | Header mapped to the `contact_person_email` CSV column.                     |

Keys with `*` are required.

**Behavior**

* The endpoint detects the delimiter and source encoding. Rows without a mapped `name` are ignored.
* A `contact_list` value resolves by exact list name. Existing contacts match by `name` and, when resolved, `contact_list_id`.
* The response is a preview and does not persist any create, update, or delete operation.
* With `delete_contacts=true`, deletion candidates are selected across all contact lists by contact name only, not just the lists represented in the file.
* The example assumes `ContactList` ID `1` is named `Professional Network` and contains Ada Lovelace as Contact ID `1` and Grace Hopper as Contact ID `2`, with no other contacts present.

**Example Request**

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

```php
$csv = "name,contact_list,phone,email\n"
    . "Ada Lovelace,Professional Network,+44 20 7946 0200,ada.updated@example.com\n"
    . "Linus Torvalds,Professional Network,,linus@example.com\n";

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/contacts/csv', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'multipart' => [
        [
            'name' => 'contact_data_csv',
            'contents' => $csv,
            'filename' => 'contacts.csv'
        ],
        [
            'name' => 'update_contacts',
            'contents' => '1'
        ],
        [
            'name' => 'delete_contacts',
            'contents' => '1'
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "new_contacts": [
      {
        "name": "Linus Torvalds",
        "contact_list_id": 1,
        "email": "linus@example.com"
      }
    ],
    "update_contacts": [
      {
        "name": "Ada Lovelace",
        "contact_list_id": 1,
        "phone": "+44 20 7946 0200",
        "email": "ada.updated@example.com",
        "id": 1
      }
    ],
    "delete_contacts": [
      {
        "id": 2,
        "contact_list_id": 1,
        "name": "Grace Hopper"
      }
    ]
  }
}
```