> 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/surveys/survey-votes.md).

# SurveyVotes

## Introduction

`SurveyVotes` record a user's submitted choices for a [Survey](/api-reference/surveys/surveys.md).

## Model Definition

**Alias**

`surveyVote`

**Relations**

| Key                     | Relation                                                                                         | Type       | Relation Field(s)       |
| ----------------------- | ------------------------------------------------------------------------------------------------ | ---------- | ----------------------- |
| `user`                  | [User](/api-reference/users.md)                                                                  | Belongs to | `user_id`               |
| `groupAccountUser`      | [User](/api-reference/users.md)                                                                  | Belongs to | `group_account_user_id` |
| `department`            | [Department](/api-reference/departments.md)                                                      | Belongs to | `department_id`         |
| `survey`                | [Survey](/api-reference/surveys/surveys.md)                                                      | Belongs to | `survey_id`             |
| `selectedAnswerOptions` | [SurveyVoteSelectedAnswerOptions](/api-reference/surveys/survey-vote-selected-answer-options.md) | Has many   | `survey_vote_id`        |

## List by Survey

List visible `SurveyVotes` for one `Survey`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/surveys/{survey}/votes`

**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. |
| `limit`     | `integer` | No limit          | Maximum number of votes.             |

**Behavior**

For anonymous surveys, voter identity fields and relations are removed. Visibility also follows the survey's `show_votes_type`.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 121,
    "user_id": 7,
    "group_account_user_id": null,
    "department_id": 6,
    "survey_id": 31,
    "selected_answer_options": [
      {
        "id": 501,
        "survey_vote_id": 121,
        "survey_answer_option_id": 81
      }
    ],
    "created_at": "2026-08-06 12:00:00",
    "updated_at": "2026-08-06 12:00:00"
  },
  {
    "id": 122,
    "user_id": 8,
    "group_account_user_id": 9,
    "department_id": 9,
    "survey_id": 31,
    "selected_answer_options": [
      {
        "id": 502,
        "survey_vote_id": 122,
        "survey_answer_option_id": 82
      }
    ],
    "created_at": "2026-08-06 12:15:00",
    "updated_at": "2026-08-06 12:15:00"
  }
]
```

## Show Current

Show the current user's `SurveyVote` for one `Survey`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/surveys/{survey}/votes/current`

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `survey`  | `integer` | Survey ID.  |

**Request Keys**

| Key         | Type     | Default           | Description                          |
| ----------- | -------- | ----------------- | ------------------------------------ |
| `relations` | `string` | Default relations | Pipe-separated relations to include. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 121,
  "user_id": 7,
  "group_account_user_id": null,
  "department_id": 6,
  "survey_id": 31,
  "selected_answer_options": [
    {
      "id": 501,
      "survey_vote_id": 121,
      "survey_answer_option_id": 81
    }
  ],
  "created_at": "2026-08-06 12:00:00",
  "updated_at": "2026-08-06 12:00:00"
}
```

## Show

Show one visible `SurveyVote`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/surveys/{survey}/votes/{surveyVote}`

**Route Parameters**

| Parameter    | Type      | Description                      |
| ------------ | --------- | -------------------------------- |
| `survey`     | `integer` | Survey ID.                       |
| `surveyVote` | `integer` | Vote ID belonging to the survey. |

**Request Keys**

| Key         | Type     | Default           | Description                          |
| ----------- | -------- | ----------------- | ------------------------------------ |
| `selects`   | `string` | All fields        | Comma-separated fields to return.    |
| `relations` | `string` | Default relations | Pipe-separated relations to include. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 121,
  "user_id": 7,
  "group_account_user_id": null,
  "department_id": 6,
  "survey_id": 31,
  "selected_answer_options": [
    {
      "id": 501,
      "survey_vote_id": 121,
      "survey_answer_option_id": 81
    }
  ],
  "created_at": "2026-08-06 12:00:00",
  "updated_at": "2026-08-06 12:00:00"
}
```

## Create

Create a new `SurveyVote`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/surveys/{survey}/votes`

**Route Parameters**

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `survey`  | `integer` | Survey ID.  |

**Request Keys**

| Key                          | Type    | Default | Description                                                                             |
| ---------------------------- | ------- | ------- | --------------------------------------------------------------------------------------- |
| `survey_answer_option_ids`\* | `array` | -       | Answer option IDs belonging to this survey. A single-choice survey accepts at most one. |

Keys with `*` are required.

**Behavior**

The authenticated user, real group-account user, department, and survey are assigned by the server. The example selection is returned in `selected_answer_options`.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 121,
    "user_id": 7,
    "group_account_user_id": null,
    "department_id": 6,
    "survey_id": 31,
    "selected_answer_options": [
      {
        "id": 501,
        "survey_vote_id": 121,
        "survey_answer_option_id": 81
      }
    ],
    "created_at": "2026-08-06 12:00:00",
    "updated_at": "2026-08-06 12:00:00"
  }
}
```

## Delete

Delete an existing `SurveyVote`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/surveys/{survey}/votes/{surveyVote}`

**Route Parameters**

| Parameter    | Type      | Description |
| ------------ | --------- | ----------- |
| `survey`     | `integer` | Survey ID.  |
| `surveyVote` | `integer` | Vote ID.    |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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

## Admin: List by Survey

List all `SurveyVotes` for one `Survey` in administration scope.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/surveys/{survey}/votes`

**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. |
| `limit`     | `integer` | No limit          | Maximum number of votes.             |

**Behavior**

Administration results include soft-deleted votes when permitted; anonymous surveys still suppress voter identity.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 121,
    "user_id": 7,
    "group_account_user_id": null,
    "department_id": 6,
    "survey_id": 31,
    "selected_answer_options": [
      {
        "id": 501,
        "survey_vote_id": 121,
        "survey_answer_option_id": 81
      }
    ],
    "created_at": "2026-08-06 12:00:00",
    "updated_at": "2026-08-06 12:00:00"
  },
  {
    "id": 122,
    "user_id": 8,
    "group_account_user_id": 9,
    "department_id": 9,
    "survey_id": 31,
    "selected_answer_options": [
      {
        "id": 502,
        "survey_vote_id": 122,
        "survey_answer_option_id": 82
      }
    ],
    "created_at": "2026-08-06 12:15:00",
    "updated_at": "2026-08-06 12:15:00",
    "deleted_at": "2026-08-06 13:00:00"
  }
]
```

## Admin: Show

Show one `SurveyVote` in administration scope.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/surveys/{survey}/votes/{surveyVote}`

**Route Parameters**

| Parameter    | Type      | Description                      |
| ------------ | --------- | -------------------------------- |
| `survey`     | `integer` | Survey ID.                       |
| `surveyVote` | `integer` | Vote ID belonging to the survey. |

**Request Keys**

| Key         | Type     | Default           | Description                          |
| ----------- | -------- | ----------------- | ------------------------------------ |
| `selects`   | `string` | All fields        | Comma-separated fields to return.    |
| `relations` | `string` | Default relations | Pipe-separated relations to include. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 122,
  "user_id": 8,
  "group_account_user_id": 9,
  "department_id": 9,
  "survey_id": 31,
  "selected_answer_options": [
    {
      "id": 502,
      "survey_vote_id": 122,
      "survey_answer_option_id": 82
    }
  ],
  "created_at": "2026-08-06 12:15:00",
  "updated_at": "2026-08-06 12:15:00"
}
```