# Polls

> How to ask the community a question in a Feed or Content space: creating the poll (options, multiple choice, deadline), voting, changing and removing a vote, who sees the results and when, editing, seeing who voted, closing, and the same actions through the API and the assistant.

A **poll** is a post with a question and 2 to 10 options for the community to vote on. It starts in a [Feed](/espacos/feed) space (as a status, where the question is the text) or a [Content](/espacos/conteudo) space (as a post, where the question is the title), and otherwise it is a post like any other: it shows up in the Feed, gets reactions and comments, can be pinned and notifies like a new post.

Polls exist only in Feed or Content spaces; in any other kind of space, the API refuses.

## What it's for

| Community | Poll |
|---|---|
| Event | *"Which month is best for APICON Rio?"*, with March, April and May |
| Online school | *"Which topic do you want in the next live class?"*, with multiple choice |
| Coworking | *"Which cleaning time bothers you least?"*, with a deadline on Friday |
| Association | A quick check before the assembly, with the results locked at the deadline |

## How it works

### Who can do what

| Action | Who |
|---|---|
| Create a poll | Owner, admin and moderator |
| Vote, change and remove a vote | Any member who sees the post |
| See the results | The team, always; other members, after voting or once the poll is closed |
| Edit, see who voted and close | Owner, admin and moderator |

The finance role votes like any member but does not create or manage polls. Someone who sees the post without signing in finds **Sign in to vote**; someone signed in who is not a member of the community sees *Only community members can vote*.

### Single or multiple choice

The card shows the **Poll** badge and, under the question, **Choose one option** or **Choose one or more options**:

- **One option**: clicking the option casts the vote.
- **Multiple choice** (when the poll was created with **Allow multiple choices**): the person ticks the options and clicks **Vote**.

After voting, the chosen option is marked **Your vote**, and **Change vote** and **Remove vote** appear. While the poll is open, people can change or remove their vote as many times as they like.

### Who sees the results

- **Members** see the bars with the percentage and the total **after voting**, or once the poll is **closed**. Before that, the card shows **Vote to see the results**.
- **The team** (owner, admin and moderator) always sees the results, whether they voted or not.

Each option's percentage is of **the people who voted**, not of the total votes. In a multiple-choice poll the sum goes over 100%: if 10 people voted and 7 ticked March, March has 70%, even if they ticked other options too. The footer says *"N people voted"* (or *No votes yet*).

### Deadline and closing

With a **Deadline**, the poll closes on its own at the chosen date and time, in the community's time zone, and the card shows **Closes on …** until then. Without a deadline, it stays open until someone on the team clicks **Close poll**.

Once closed, it gets the **Closed** badge and the line **Closed on …**: nobody can vote, change or remove a vote any more, and everyone sees the final results. The votes are kept. **A closed poll cannot be reopened.**

### Votes are anonymous to members

Members only see the numbers. Who voted for what is visible only to the team, in **See who voted**.

### Notification

A poll follows the path of a new post in the space: the same notifications and e-mails as a status in the Feed or a post in Content, according to each person's preferences. Voting notifies nobody.

## Step by step

### Create a poll

*Role: owner, admin or moderator.*

1. Open the Feed or Content space.
2. In the header, click the arrow next to **New Status** (in Content, **New Content**) and choose **New poll**. The same menu holds **Import content**, which only the owner and the admin see.
3. Fill in:
   - **Question**: in the Feed, it is the status text (up to 500 characters); in Content, it is the post title (up to 255).
   - **Options**: 2 to 10, up to 100 characters each, no repeats. **Add option** adds one more; the **×** removes one.
   - **Allow multiple choices**: each person can tick more than one option.
   - **Who sees it**, in the Feed only: **Public** (the default), **Members** or **Subscribers**, as in **New Status**. In Content there is no choice: the poll is public, like **New Content**.
   - **Deadline (optional)**: date and time in the community's time zone, which the screen shows. **No deadline** removes it.
4. Click **Publish poll**.

In Content, the post starts with only the question as its title. To add text under it, edit the post afterwards.

### Vote

1. On the poll card, click the option (in a single-choice poll, that already votes).
2. In a multiple-choice poll, tick the options and click **Vote**.
3. To change, **Change vote**; to give up, **Remove vote**.

### Edit a poll

*Role: owner, admin or moderator.*

In the card's **⋮** menu, **Edit poll**.

- **Before the first vote**, everything can change: the options (text, order, adding and removing), **Allow multiple choices** and the deadline.
- **After the first vote**, the options no longer change, neither text nor order: the fields show disabled (*"There are votes already: the options can no longer change, so what people chose stays the same."*), and **Allow multiple choices** is locked. The question stays editable through the post, and the deadline can still be set, moved or removed.
- **Closed with no votes**, only the text of the options.

The question is the post's text (or title): to change it, edit the post.

### See who voted

*Role: owner, admin or moderator.*

In the card's **⋮** menu, **See who voted**. The **Who voted** dialog lists the people, latest vote first, with each person's options. **Filter by option** shows only who chose one of them.

### Close

*Role: owner, admin or moderator.*

1. In the card's **⋮** menu, **Close poll**.
2. Confirm with **Close**. There is no way back: the poll cannot be reopened.

## Examples

**Event date.** In the Home Feed: *"Which month is best for APICON Rio?"*, with March, April and May, single choice and a deadline at the end of the month. Pin it to the top so everyone sees it.

**Next class topic.** In the class's Content space: *"Which topic do you want in the next live class?"*, with five topics and **Allow multiple choices**. The team follows the results from the first vote and closes it when it decides.

## Common errors and how to fix them

| Situation | What to do |
|---|---|
| **New poll** does not show in the menu | Only the owner, the admin and the moderator create polls |
| *The poll needs at least 2 options.* or *The poll can have up to 10 options.* | Adjust the number of options |
| *Some options are repeated.* | Two options have the same text (case does not count): change one |
| *Choose a deadline in the future.* | The deadline has passed; pick another date or leave it without a deadline |
| The options can't be edited | The poll already has votes: the options stay as they were voted on. For another question, create another poll |
| The member doesn't see the results | They haven't voted yet and the poll is open |
| Voting doesn't work | The poll is closed |

## Frequently asked questions

**Can a closed poll be reopened?**
No. To ask again, create another one.

**Can an existing post become a poll?**
No. The poll is born with the post, in **New poll**.

**Does deleting the post delete the poll?**
Yes, the poll goes with the post.

**Do members know what I voted for?**
No. Only the team sees who voted for what.

## Through the assistant

The assistant creates, votes on and follows polls with the same rules:

- `create_poll`: creates it in the Feed (the question is the text) or in Content (the question is the title). Owner, admin and moderator, without confirmation.
- `get_poll`: the results. Any role; for people who haven't voted, the numbers stay hidden until the poll closes.
- `vote_poll` (by option or by its text) and `retract_poll_vote`: in the name of whoever connected, without confirmation.
- `update_poll`: edits, and asks for confirmation when the options change. `close_poll`: closes, always with confirmation. `list_poll_votes`: who voted. These three are for the team.

Ask like this: *"Create a poll in the Feed asking which month is best for APICON Rio, with March, April and May."* In Claude, the recipe **Ask the community (poll)** builds the request. See [Tools · Content](/mcp/ferramentas-conteudo#polls).

## In the API

The poll goes in the `poll` field of `POST /api/status` (Feed) and `POST /api/content` (Content): `options` (2 to 10 texts), `allowMultiple` and `closesAt` (optional, in the future). Only owner, admin and moderator; any other role gets `403` with `param: "poll"`, and nothing is saved. `poll` comes in the items of `GET /api/feed`, in statuses, in content and in recommendations.

| Route | What it does | Who |
|---|---|---|
| `GET /api/polls/{id}` | The results, as the person may see them | Whoever sees the post |
| `POST /api/polls/{id}/vote` | Votes (`optionIds`); voting again replaces the vote | A member who sees the post |
| `DELETE /api/polls/{id}/vote` | Removes the vote | A member who sees the post |
| `PUT /api/polls/{id}` | Edits options, `allowMultiple` and `closesAt` | Owner, admin and moderator |
| `POST /api/polls/{id}/close` | Closes, with no way back | Owner, admin and moderator |
| `GET /api/polls/{id}/votes` | Who voted, with an `optionId` filter | Owner, admin and moderator |

For someone who may not see the results, `resultsVisible` is `false`, and `votes`, `percentage` and `totalVoters` are `null` (hidden, not zero).

| Error | When |
|---|---|
| `400` | A space that is neither Feed nor Content, fewer than 2 or more than 10 options, an empty option or one over 100 characters, a repeated option, a past or invalid deadline, more than one option in a single-choice vote |
| `403` | The role does not create or manage polls, or the person is not a member of the community |
| `404` | The poll does not exist or belongs to another community |
| `409` | `closed` (the poll is closed) or `optionsLocked` (changing the options, text or order included, after the first vote); also when trying to change `allowMultiple` with votes |

See [Polls](/api/referencia/polls).

## Related

- [Feed](/espacos/feed)
- [Content](/espacos/conteudo)
- [Roles and permissions](/conceitos/papeis-e-permissoes)
- [Tools · Content](/mcp/ferramentas-conteudo#polls)