Surveys

Introduction

Surveys collect one or more selections from targeted users and departments.

The description field uses the shared Rich Text HTML format.

Model Definition

Alias

survey

Computed Properties

• hash - Hashed survey ID.

• url - Stable survey URL.

• answer_options_summary - Vote count per answer option when explicitly appended.

• current_vote - Current user's vote when explicitly appended.

Capabilities

• Targetables - Explicit users and departments or a supported targetable parent define eligible voters.

• Entity Permissions - Direct administration grants supplement module permissions.

• URL Context - Survey URLs resolve to access-checked context.

• Translations - Localizes title and description; examples use en-US.

Relations

Key	Relation	Type	Relation Field(s)
user	User	Belongs to	user_id
folder	Folder	Belongs to	folder_id
targetable	Supported targetable entity	Morph to	targetable_type, targetable_id
users	Users	Belongs to many	survey_user
departments	Departments	Belongs to many	department_survey
surveyAnswerOptions	SurveyAnswerOptions	Has many	survey_id
surveyVotes	SurveyVotes	Has many	survey_id
currentVote	SurveyVote	Has one	survey_id, department_id, user_id
entityPermissions	EntityPermissions	Morph many	target_entity, target_entity_id

Types

• singleChoice - Allows one selected answer option per vote.

• multipleChoice - Allows multiple selected answer options per vote.

Show Votes Types

• none - Does not expose vote results to voters.

• always - Exposes vote results while the survey is available.

• after_vote - Exposes vote results after the current voter has submitted a vote.

• after_survey_end - Exposes vote results after the survey has ended.

Targetable Types

• chatMessage - Targets the audience of a ChatMessage.

• infoboardPost - Targets the audience of an InfoboardPost.

• manualEntry - Targets the audience of a ManualEntry.

List

List visible Surveys.

Definition

GET /api/surveys

Request Keys

Key	Type	Default	Description
selects	string	All fields	Comma-separated fields to return.
relations	string	Default relations	Pipe-separated relations to include.
appends	string	Default appends	Pipe-separated computed properties such as answer_options_summary or current_vote.
limit	integer	No limit	Maximum number of surveys.
filters	object	No filters	Value filters.

Example Request

PHP

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

Example Response

[
  {
    "id": 31,
    "user_id": 7,
    "folder_id": 10,
    "targetable_id": null,
    "targetable_type": null,
    "lang_id": "en-US",
    "type": "singleChoice",
    "active": true,
    "title": "Cafeteria satisfaction",
    "description": "<p>How satisfied are you with the cafeteria?</p>",
    "show_votes_type": "after_vote",
    "assign_mode": "any_of",
    "user_confirmation_required": false,
    "one_vote_per_department": false,
    "anonymous": false,
    "sort_number": 1,
    "start_date": "2026-08-01 00:00:00",
    "end_date": "2026-08-31 23:59:59",
    "hash": "qR"
  },
  {
    "id": 32,
    "user_id": 8,
    "folder_id": null,
    "targetable_id": 204,
    "targetable_type": "infoboardPost",
    "lang_id": "en-US",
    "type": "multipleChoice",
    "active": true,
    "title": "Choose the next training topics",
    "description": "<p>Select every topic that interests you.</p>",
    "show_votes_type": "after_survey_end",
    "assign_mode": null,
    "user_confirmation_required": true,
    "one_vote_per_department": true,
    "anonymous": true,
    "sort_number": 2,
    "start_date": null,
    "end_date": "2026-09-15 17:00:00",
    "hash": "rS"
  }
]

Show

Show one visible Survey.

Definition

GET /api/surveys/{survey}

Route Parameters

Parameter	Type	Description
survey	integer	Survey ID.

Request Keys

Key	Type	Default	Description
selects	string	All fields	Comma-separated fields to return.
relations	string	Default relations	Pipe-separated relations to include.
appends	string	Default appends	Pipe-separated computed properties.

Behavior

For anonymous surveys, voter-specific attributes and relations are removed from nested vote data.

Example Request

PHP

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

Example Response

{
  "id": 31,
  "user_id": 7,
  "folder_id": 10,
  "targetable_id": null,
  "targetable_type": null,
  "lang_id": "en-US",
  "type": "singleChoice",
  "active": true,
  "title": "Cafeteria satisfaction",
  "description": "<p>How satisfied are you with the cafeteria?</p>",
  "show_votes_type": "after_vote",
  "assign_mode": "any_of",
  "user_confirmation_required": false,
  "one_vote_per_department": false,
  "anonymous": false,
  "sort_number": 1,
  "start_date": "2026-08-01 00:00:00",
  "end_date": "2026-08-31 23:59:59",
  "hash": "qR"
}

Admin: List

List all Surveys in administration scope.

Definition

GET /api/administration/surveys

Request Keys

Key	Type	Default	Description
selects	string	All fields	Comma-separated fields to return.
relations	string	Default relations	Pipe-separated relations to include.
appends	string	Default appends	Pipe-separated computed properties such as answer_options_summary or current_vote.
limit	integer	No limit	Maximum number of surveys.
filters	object	No filters	Value filters.

Behavior

Administration results can include inactive and soft-deleted surveys.

Example Request

PHP

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

Example Response

[
  {
    "id": 31,
    "user_id": 7,
    "folder_id": 10,
    "targetable_id": null,
    "targetable_type": null,
    "lang_id": "en-US",
    "type": "singleChoice",
    "active": true,
    "title": "Cafeteria satisfaction",
    "description": "<p>How satisfied are you with the cafeteria?</p>",
    "show_votes_type": "after_vote",
    "assign_mode": "any_of",
    "user_confirmation_required": false,
    "one_vote_per_department": false,
    "anonymous": false,
    "sort_number": 1,
    "start_date": "2026-08-01 00:00:00",
    "end_date": "2026-08-31 23:59:59",
    "hash": "qR"
  },
  {
    "id": 32,
    "user_id": 8,
    "folder_id": null,
    "targetable_id": 204,
    "targetable_type": "infoboardPost",
    "lang_id": "en-US",
    "type": "multipleChoice",
    "active": false,
    "title": "Choose the next training topics",
    "description": "<p>Select every topic that interests you.</p>",
    "show_votes_type": "after_survey_end",
    "assign_mode": null,
    "user_confirmation_required": true,
    "one_vote_per_department": true,
    "anonymous": true,
    "sort_number": 2,
    "start_date": null,
    "end_date": "2026-09-15 17:00:00",
    "hash": "rS",
    "deleted_at": "2026-08-02 09:00:00"
  }
]

Admin: Show

Show one Survey in administration scope.

Definition

GET /api/administration/surveys/{survey}

Route Parameters

Parameter	Type	Description
survey	integer	Survey ID.

Request Keys

Key	Type	Default	Description
selects	string	All fields	Comma-separated fields to return.
relations	string	Default relations	Pipe-separated relations to include.
appends	string	Default appends	Pipe-separated computed properties.

Example Request

PHP

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

Example Response

{
  "id": 32,
  "user_id": 8,
  "folder_id": null,
  "targetable_id": 204,
  "targetable_type": "infoboardPost",
  "lang_id": "en-US",
  "type": "multipleChoice",
  "active": true,
  "title": "Choose the next training topics",
  "description": "<p>Select every topic that interests you.</p>",
  "show_votes_type": "after_survey_end",
  "assign_mode": null,
  "user_confirmation_required": true,
  "one_vote_per_department": true,
  "anonymous": true,
  "sort_number": 2,
  "start_date": null,
  "end_date": "2026-09-15 17:00:00",
  "hash": "rS"
}

Admin: Create

Create a new Survey.

Definition

POST /api/administration/surveys

Request Keys

Key	Type	Default	Description
lang_id	string	System language	Language key. Use en-US for this example.
type*	string	-	Selects one of the supported Types.
title*	string	-	Survey title.
description	string | null	null	HTML description.
active	boolean	false	Whether the survey can be answered.
show_votes_type	string	System default	Selects one of the supported Show Votes Types.
assign_mode	string | null	Default assignment mode	Assignment mode; ignored for a targetable parent.
user_ids	array | null	[]	Directly targeted user IDs.
department_ids	array | null	[]	Directly targeted department IDs.
targetable_type	string | null	null	Supported targetable morph alias.
targetable_id	integer | null	null	Targetable entity ID.
user_confirmation_required	boolean	false	Require confirmed user identity.
one_vote_per_department	boolean	false	Limit voting by department instead of user.
anonymous	boolean	false	Suppress voter information in permitted responses.
start_date	datetime | null	null	Voting start.
end_date	datetime | null	null	Voting end.
folder_id	integer | null	null	Folder ID.
sort_number	integer	Auto	Display order.
entity_permissions	object	Unrestricted	Entity Permissions.

Keys with * are required for creation.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/administration/surveys', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'lang_id' => 'en-US',
        'type' => 'singleChoice',
        'title' => 'Cafeteria satisfaction',
        'description' => '<p>How satisfied are you with the cafeteria?</p>',
        'active' => true,
        'show_votes_type' => 'after_vote',
        'assign_mode' => 'any_of',
        'user_ids' => [7, 8],
        'department_ids' => [6, 9],
        'user_confirmation_required' => false,
        'one_vote_per_department' => false,
        'anonymous' => false,
        'start_date' => '2026-08-01 00:00:00',
        'end_date' => '2026-08-31 23:59:59',
        'folder_id' => 10,
        'sort_number' => 1
    ]
]);

Example Response

{
  "status": "success",
  "data": {
    "id": 31,
    "user_id": 7,
    "folder_id": 10,
    "targetable_id": null,
    "targetable_type": null,
    "lang_id": "en-US",
    "type": "singleChoice",
    "active": true,
    "title": "Cafeteria satisfaction",
    "description": "<p>How satisfied are you with the cafeteria?</p>",
    "show_votes_type": "after_vote",
    "assign_mode": "any_of",
    "user_confirmation_required": false,
    "one_vote_per_department": false,
    "anonymous": false,
    "sort_number": 1,
    "start_date": "2026-08-01 00:00:00",
    "end_date": "2026-08-31 23:59:59",
    "hash": "qR"
  }
}

Admin: Update

Update an existing Survey.

Definition

PUT /api/administration/surveys/{survey}

Route Parameters

Parameter	Type	Description
survey	integer	Survey ID.

Request Keys

Key	Type	Default	Description
lang_id	string	System language	Language key. Use en-US for this example.
type*	string	-	Selects one of the supported Types.
title*	string	-	Survey title.
description	string | null	null	HTML description.
active	boolean	false	Whether the survey can be answered.
show_votes_type	string	System default	Selects one of the supported Show Votes Types.
assign_mode	string | null	Default assignment mode	Assignment mode; ignored for a targetable parent.
user_ids	array | null	[]	Directly targeted user IDs.
department_ids	array | null	[]	Directly targeted department IDs.
targetable_type	string | null	null	Supported targetable morph alias.
targetable_id	integer | null	null	Targetable entity ID.
user_confirmation_required	boolean	false	Require confirmed user identity.
one_vote_per_department	boolean	false	Limit voting by department instead of user.
anonymous	boolean	false	Suppress voter information in permitted responses.
start_date	datetime | null	null	Voting start.
end_date	datetime | null	null	Voting end.
folder_id	integer | null	null	Folder ID.
sort_number	integer	Auto	Display order.
entity_permissions	object	Unrestricted	Entity Permissions.

Behavior

After the first vote, configured immutable attributes such as survey type cannot be changed. Use Reset when those settings must change and existing votes may be removed.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/surveys/31', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'lang_id' => 'en-US',
        'title' => 'Cafeteria and catering satisfaction',
        'description' => '<p>How satisfied are you with food services?</p>',
        'end_date' => '2026-09-07 23:59:59',
        'user_ids' => [7, 8],
        'department_ids' => [6, 9]
    ]
]);

Example Response

{
  "status": "success",
  "data": {
    "id": 31,
    "user_id": 7,
    "folder_id": 10,
    "targetable_id": null,
    "targetable_type": null,
    "lang_id": "en-US",
    "type": "singleChoice",
    "active": true,
    "title": "Cafeteria and catering satisfaction",
    "description": "<p>How satisfied are you with food services?</p>",
    "show_votes_type": "after_vote",
    "assign_mode": "any_of",
    "user_confirmation_required": false,
    "one_vote_per_department": false,
    "anonymous": false,
    "sort_number": 1,
    "start_date": "2026-08-01 00:00:00",
    "end_date": "2026-09-07 23:59:59",
    "hash": "qR"
  }
}

Admin: Reset

Reset an existing Survey.

Definition

PUT /api/administration/surveys/{survey}/reset

Route Parameters

Parameter	Type	Description
survey	integer	Survey ID.

Request Keys

Key	Type	Default	Description
lang_id	string	System language	Language key. Use en-US for this example.
type*	string	-	Selects one of the supported Types.
title*	string	-	Survey title.
description	string | null	null	HTML description.
active	boolean	false	Whether the survey can be answered.
show_votes_type	string	System default	Selects one of the supported Show Votes Types.
assign_mode	string | null	Default assignment mode	Assignment mode; ignored for a targetable parent.
user_ids	array | null	[]	Directly targeted user IDs.
department_ids	array | null	[]	Directly targeted department IDs.
targetable_type	string | null	null	Supported targetable morph alias.
targetable_id	integer | null	null	Targetable entity ID.
user_confirmation_required	boolean	false	Require confirmed user identity.
one_vote_per_department	boolean	false	Limit voting by department instead of user.
anonymous	boolean	false	Suppress voter information in permitted responses.
start_date	datetime | null	null	Voting start.
end_date	datetime | null	null	Voting end.
folder_id	integer | null	null	Folder ID.
sort_number	integer	Auto	Display order.
entity_permissions	object	Unrestricted	Entity Permissions.

Behavior

Applies the supplied changes and soft-deletes every existing vote for the survey. Omitted settings keep their current values.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/surveys/31/reset', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'type' => 'multipleChoice',
        'show_votes_type' => 'after_survey_end',
        'anonymous' => true,
        'user_ids' => [7, 8],
        'department_ids' => [6, 9]
    ]
]);

Example Response

{
  "status": "success",
  "data": {
    "id": 31,
    "user_id": 7,
    "folder_id": 10,
    "targetable_id": null,
    "targetable_type": null,
    "lang_id": "en-US",
    "type": "multipleChoice",
    "active": true,
    "title": "Cafeteria satisfaction",
    "description": "<p>How satisfied are you with the cafeteria?</p>",
    "show_votes_type": "after_survey_end",
    "assign_mode": "any_of",
    "user_confirmation_required": false,
    "one_vote_per_department": false,
    "anonymous": true,
    "sort_number": 1,
    "start_date": "2026-08-01 00:00:00",
    "end_date": "2026-08-31 23:59:59",
    "hash": "qR"
  }
}

Admin: Delete

Delete an existing Survey.

Definition

DELETE /api/administration/surveys/{survey}

Route Parameters

Parameter	Type	Description
survey	integer	Survey ID.

Example Request

PHP

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

Example Response

{
  "status": "success",
  "data": null
}

Admin: List Targeted Users

List users targeted by one Survey.

Definition

GET /api/administration/surveys/{survey}/targeted/users

Route Parameters

Parameter	Type	Description
survey	integer	Survey ID.

Request Keys

Key	Type	Default	Description
selects	string	All fields	Comma-separated user fields to return.
limit	integer	No limit	Maximum number of users.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/administration/surveys/31/targeted/users', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

[
  {
    "id": 7,
    "firstname": "Ada",
    "lastname": "Lovelace",
    "email": "[e-mail]",
    "active": true
  },
  {
    "id": 8,
    "firstname": "Grace",
    "lastname": "Hopper",
    "email": "[e-mail]",
    "active": true
  }
]

Admin: List Targeted Departments

List departments targeted by one Survey.

Definition

GET /api/administration/surveys/{survey}/targeted/departments

Route Parameters

Parameter	Type	Description
survey	integer	Survey ID.

Request Keys

Key	Type	Default	Description
selects	string	All fields	Comma-separated department fields to return.
limit	integer	No limit	Maximum number of departments.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/administration/surveys/31/targeted/departments', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

[
  {
    "id": 6,
    "name": "Engineering",
    "active": true
  },
  {
    "id": 9,
    "name": "Product",
    "active": true
  }
]