Contacts

Introduction

Contacts store organization and contact-person details within a ContactList.

The notes field uses the shared Rich Text HTML format. All endpoints require the contact-lists-show permission.

Model Definition

Relations

Key	Relation	Type	Relation Field(s)
user	User	Belongs to	user_id
contactList	ContactList	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

GET /api/contacts

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 to filter the selected field.
search_type	string	name	Contact field 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.

Behavior

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

Example Request

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

Example Response

[
  {
    "id": 1,
    "user_id": 3,
    "contact_list_id": 1,
    "name": "Example Logistics Ltd.",
    "phone": "[phone]",
    "fax": "[phone]",
    "email": "[e-mail]",
    "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": "[phone]",
    "contact_person_mobile_phone": "[phone]",
    "contact_person_email": "[e-mail]",
    "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": "[phone]",
    "fax": null,
    "email": "[e-mail]",
    "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

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

Behavior

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

Example Request

PHP

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

Example Response

{
  "id": 1,
  "user_id": 3,
  "contact_list_id": 1,
  "name": "Example Logistics Ltd.",
  "phone": "[phone]",
  "fax": "[phone]",
  "email": "[e-mail]",
  "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": "[phone]",
  "contact_person_mobile_phone": "[phone]",
  "contact_person_email": "[e-mail]",
  "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

POST /api/contacts

Request Keys

Key	Type	Default	Description
contact_list_id*	integer	-	Parent ContactList 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 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.

• email and contact_person_email follow the shared Email Addresses rules.

• Empty optional contact values are normalized to null.

Example Request

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' => '[phone]',
        'fax' => null,
        'email' => '[e-mail]',
        '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' => '[phone]',
        'contact_person_mobile_phone' => '[phone]',
        'contact_person_email' => '[e-mail]'
    ]
]);

Example Response

{
  "status": "success",
  "data": {
    "id": 3,
    "user_id": 3,
    "contact_list_id": 1,
    "name": "Example Engineering Inc.",
    "phone": "[phone]",
    "fax": null,
    "email": "[e-mail]",
    "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": "[phone]",
    "contact_person_mobile_phone": "[phone]",
    "contact_person_email": "[e-mail]",
    "created_at": "2026-08-07 11:00:00",
    "updated_at": "2026-08-07 11:00:00"
  }
}

Update

Update an existing Contact.

Definition

PUT /api/contacts/{id}

Route Parameters

Parameter	Type	Description
id	integer	Contact ID.

Request Keys

Key	Type	Description
contact_list_id	integer	Parent ContactList 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 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.

• Supplied email and contact_person_email values follow the shared Email Addresses rules.

• Empty optional contact values are normalized to null.

Example Request

PHP

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

Example Response

{
  "status": "success",
  "data": {
    "id": 3,
    "user_id": 3,
    "contact_list_id": 1,
    "name": "Example Engineering Inc.",
    "phone": "[phone]",
    "fax": null,
    "email": "[e-mail]",
    "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": "[phone]",
    "contact_person_mobile_phone": null,
    "contact_person_email": "[e-mail]",
    "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

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

PHP

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

Example Response

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

Parse CSV

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

Definition

POST /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 not represented by the resolved CSV identities in delete_contacts.
whitespace_to_null	boolean	false	Convert blank nullable fields to null.
include_row_results	boolean	false	Add the per-row preview report to data.rows.
contact_list	string	contact_list	Header mapped to the contact_list CSV column.
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, but a contact is protected by its resolved name and list identity. A namesake in a different list can therefore be proposed for deletion.

• Deletion previews reject an empty file or a populated row without a mapped name instead of proposing every contact for deletion.

• Contacts and lists owned by the reserved intratool administration account are excluded from CSV changes. Content owned by the intratool service account remains importable.

• With include_row_results=true, data.rows reports each non-empty CSV row with its record number, available name and contact_list labels, action, index, status, reason, and errors. The status and candidate-array index follow the User CSV preview rules. Failed or excluded rows still protect possible matching contacts from being proposed for deletion. Omitting this option preserves the three candidate arrays without a row report.

• 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

PHP

$csv = "name,contact_list,phone,email\n"
    . "Ada Lovelace,Professional Network,[phone],[e-mail]\n"
    . "Linus Torvalds,Professional Network,,[e-mail]\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'
        ]
    ]
]);

Example Response

{
  "status": "success",
  "data": {
    "new_contacts": [
      {
        "name": "Linus Torvalds",
        "contact_list_id": 1,
        "email": "[e-mail]"
      }
    ],
    "update_contacts": [
      {
        "name": "Ada Lovelace",
        "contact_list_id": 1,
        "phone": "[phone]",
        "email": "[e-mail]",
        "id": 1
      }
    ],
    "delete_contacts": [
      {
        "id": 2,
        "contact_list_id": 1,
        "name": "Grace Hopper"
      }
    ]
  }
}