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.

Scope: vote | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

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's Bitrix24 permissions still apply. Chat polls are managed by the message author; Feed polls require post management rights.

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.

Finding a poll

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

In chat 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 is not recognized, source may be omitted.

Poll object

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, including the author and administrators, can see who voted: 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 in data.poll. On such a retry, data.voteId arrives as a new number that matches no poll, so take the poll number from data.poll.voteId. Use a new key for a new poll. Bitrix24 does not compare bodies: keep the question, answers and settings unchanged on a retry. If idempotencyKey is omitted, the server generates a new UUID for each request. Duplicate protection depends on the Bitrix24 version.

The platform does not retry writes automatically. 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 the post or message that contains the poll, using its existing endpoint.

Quick start

Read a poll by its attachment ID:

curl -H "X-Api-Key: YOUR_API_KEY" "https://vibecode.bitrix24.com/v1/polls/25"

Response fields: Get a poll.

Full example

Create a chat poll, vote, read the results and stop the poll:

const BASE = 'https://vibecode.bitrix24.com/v1'
const headers = { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }

async function call(method, path, body) {
  const res = await fetch(`${BASE}${path}`, {
    method,
    headers: body ? headers : { 'X-Api-Key': headers['X-Api-Key'] },
    body: body ? JSON.stringify(body) : undefined,
  })
  const json = await res.json()
  if (!json.success) throw new Error(`${res.status} ${json.error.code}: ${json.error.message}`)
  return json
}

// 1. Create a chat poll
const created = await call('POST', '/chats/chat5/polls', {
  question: 'When?',
  answers: ['Now', 'Later'],
  idempotencyKey: crypto.randomUUID(),
})
const poll = created.data.poll
console.log('Poll', poll.id, 'in message', created.data.messageId)

// 2. Vote for the first answer
const firstAnswer = poll.questions[0].answers[0].id
await call('POST', `/polls/${poll.id}/vote`, { answerIds: [firstAnswer] })

// 3. Read the results
const results = await call('GET', `/polls/${poll.id}/results`)
for (const answer of results.data.questions[0].answers) {
  console.log(answer.text, answer.votesCount, `${answer.percent}%`)
}

// 4. Stop the poll
await call('POST', `/polls/${poll.id}/stop`)
const finished = await call('GET', `/polls/${poll.id}`)
console.log('Status:', finished.data.status)

Endpoint reference

Error codes

Poll errors

System errors

Full list of shared API errors: Errors.

See also

• List posts
• Messages
• Chat discovery
• Batch calls