# Polls

Feed polls **cannot be created** through the API: the Bitrix24 REST API does not officially support creating a Feed poll. Existing polls can be read and managed. Chat polls can be created through the API.

## Access

All operations require the `vote` scope. Creating a poll in a personal chat (`dialogId` is a user ID or `me`) also requires `im`; `vote` alone is sufficient for `chatN`. The current user must have the corresponding Bitrix24 permissions. Chat polls are managed by the message author; Feed polls require post management rights.

| Key | Read | Write |
| --- | --- | --- |
| Ordinary read-only key | All four GET operations | Denied |
| Cowork key with read-only access to the Bitrix24 account | Denied | Denied |
| Company key | Denied | Denied |

All four GET operations read the poll and subscribe the user to Bitrix24 events, so these operations are unavailable to a Cowork key that forbids writes to the Bitrix24 account. Poll methods are also unavailable through [batch requests](/docs/batch).

## Operations

| Method and path | Description |
| --- | --- |
| `POST /v1/chats/:dialogId/polls` | [Create a chat poll](/docs/polls/create) |
| `GET /v1/polls/:pollId` | [Get a poll](/docs/polls/get) |
| `GET /v1/polls` | [Find polls by posts or messages](/docs/polls/list) |
| `GET /v1/polls/:pollId/results` | [Poll results](/docs/polls/results) |
| `GET /v1/polls/:pollId/answers/:answerId/voters` | [List voters for an answer](/docs/polls/voters) |
| `POST /v1/polls/:pollId/vote` | [Vote or revote](/docs/polls/vote) |
| `DELETE /v1/polls/:pollId/vote` | [Recall a vote](/docs/polls/recall) |
| `POST /v1/polls/:pollId/stop` | [Stop a poll](/docs/polls/stop) |
| `POST /v1/polls/:pollId/resume` | [Resume a poll](/docs/polls/resume) |

## Finding a poll

In the [post list](/docs/feed/posts/list) (`GET /v1/posts`), select entries with `hasPoll: true`. Then pass the post IDs to `GET /v1/polls?postIds=42`.

In [chat messages](/docs/chats/messages) (`GET /v1/chats/:dialogId/messages`), a poll has `data.messages[].params.componentId = "VoteMessage"`. The value of `params.componentParams.id` is the Bitrix24 poll number, `voteId`. To find its attachment, pass the **message ID**, rather than `voteId`, to `GET /v1/polls?messageIds=42`.

In the returned object, `id` is the attachment ID (`pollId` in API paths). It differs from `voteId`, the post ID and the message ID. If the attachment connector is not recognized, `source` may be omitted.

## Poll object

| Field | Type | Description |
| --- | --- | --- |
| `id` | number | Attachment ID used as `pollId` |
| `voteId` | number | Bitrix24 poll number |
| `source` | object | Optional: `{type: "post", postId}` or `{type: "chatMessage", messageId}` |
| `status` | string | `active` or `finished` |
| `anonymous` | boolean | Whether the poll is anonymous |
| `allowRevote` | boolean | Whether revoting is allowed |
| `resultsHidden` | boolean | Bitrix24 hidden-results flag |
| `resultsVisible` | boolean | Whether results are visible to the current user under Bitrix24 rules |
| `votersCount` | number \| null | Participant counter |
| `questions` | array | Active questions and answers only, in Bitrix24 sort order |
| `questions[].id` | number | Question ID |
| `questions[].text` | string | Question text |
| `questions[].multipleChoice` | boolean | Whether multiple answers can be selected |
| `questions[].required` | boolean | Whether an answer is required |
| `questions[].votesCount` | number \| null | Question vote counter |
| `questions[].answers` | array | Answer choices |
| `questions[].answers[].id` | number | Answer ID for voting and voter lists |
| `questions[].answers[].text` | string | Answer text |
| `questions[].answers[].votesCount` | number \| null | Answer vote counter |
| `questions[].answers[].percent` | number \| null | Percentage supplied by Bitrix24 |
| `myVote.voted` | boolean | Whether the current user has voted |
| `myVote.answerIds` | number[] | Answers selected by the current user |
| `permissions.canVote` | boolean | Whether voting is permitted |
| `permissions.canRevote` | boolean | Whether revoting is permitted |
| `permissions.canManage` | boolean | Whether management is permitted |

## Results and anonymity

Results are hidden when `resultsHidden: true`, or while the poll is active and the user can vote but has not voted. The exception is the poll author when Bitrix24 reports authorship (chat polls on Bitrix24 versions that support reporting authorship); post or message management rights do not reveal results. The author of a Feed poll sees hidden results in the Bitrix24 interface. Missing permission data hides results; a finished poll without hidden results remains visible. When `resultsVisible: false`, `votersCount`, `questions[].votesCount`, `questions[].answers[].votesCount` and `percent` are `null`, and answers have `voters: []` and `votersComplete: false` in every API response containing a poll object.

In an anonymous poll, nobody can see voter identities, including the author and administrators: counters are available when `resultsVisible: true`. In results, `voters` is always empty and `votersComplete` is `false`. Results for a non-anonymous poll include a limited voter preview for each answer; use the separate operation for the full list. Counters are not cached.

The API does not return an Excel report or result links. Export the report in the Bitrix24 interface.

## Handling writes

The creation `idempotencyKey` must be a UUID. On supported Bitrix24 versions, repeating the same key with the same body returns the existing poll. Use a new key for a new poll. Bitrix24 does not compare bodies: keep the question, answers and settings unchanged on a retry. If omitted, the server generates a new UUID for each request. Duplicate protection depends on the Bitrix24 version.

The platform never automatically replays writes. After `502 POLL_CREATE_OUTCOME_UNKNOWN`, inspect the chat first: the message may already exist. After other `502 …_OUTCOME_UNKNOWN` errors, read the poll and decide whether another write is needed. Do not immediately create a new key after an unknown outcome.

When revoting in the Feed, if someone edits the poll during the vote, Bitrix24 may erase the previous vote, just as in the interface. Check `myVote` after an error.

## Deletion

There is no separate poll deletion operation. Delete its containing [post](/docs/feed/posts/delete) or [message](/docs/chats/messages/delete) using the existing route.