> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenzap.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Polls

> How to create polls and record votes programmatically using the Zenzap API.

Polls are posted as messages in a topic. When you create a poll, each option is stored with a server-generated 6-character ID. You use those IDs when submitting votes.

## Create a Poll

```
POST https://api.zenzap.co/v2/polls
```

The bot must be a member of the topic. A poll message is sent on behalf of the bot.

```json theme={"theme":"github-dark"}
{
  "topicId": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Which release should we prioritize?",
  "options": [
    "Bug fixes",
    "New features",
    "Performance improvements"
  ],
  "selectionType": "single"
}
```

**Response — `201 Created`:**

```json theme={"theme":"github-dark"}
{
  "id": "770e8400-e29b-41d4-a716-446655440099",
  "topicId": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Which release should we prioritize?",
  "options": [
    { "id": "a1b2c3", "text": "Bug fixes" },
    { "id": "d4e5f6", "text": "New features" },
    { "id": "g7h8i9", "text": "Performance improvements" }
  ],
  "selectionType": "single",
  "status": "active",
  "createdAt": 1699564800000
}
```

Save the `id` (the poll ID) and the `options[].id` values — you need them to submit votes.

## Vote on a Poll

```
POST https://api.zenzap.co/v2/polls/{pollId}/votes
```

Use the poll `id` from the create response as the `pollId` path parameter, and one of the `options[].id` values as `optionId`.

```json theme={"theme":"github-dark"}
{
  "optionId": "a1b2c3"
}
```

**Response — `201 Created`:**

```json theme={"theme":"github-dark"}
{
  "id": "770e8400-e29b-41d4-a716-446655440099_a1b2c3_b@f951b968-bf80-4ee6-bbbe-6ca338f57fc6",
  "attachmentId": "770e8400-e29b-41d4-a716-446655440099",
  "optionId": "a1b2c3",
  "createdAt": 1699564800000
}
```

Each `{pollId, optionId, voter}` combination is idempotent — re-submitting the same vote is a no-op.

## Delete a Vote

```
DELETE https://api.zenzap.co/v2/polls/{pollId}/votes/{voteId}
```

Use the `id` from the vote creation response as `voteId`.

**Response — `204 No Content`** (empty body on success)

**`404`** is returned if the vote is not found.

## Request Fields

### POST /v2/polls

| Field           | Type                       | Required | Description                                                                                |
| --------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `topicId`       | string (UUID)              | Yes      | Topic to post the poll in. The bot must be a member.                                       |
| `question`      | string                     | Yes      | Poll question / title. Max 500 characters.                                                 |
| `options`       | string\[]                  | Yes      | Answer option texts. Min 2, max 10. Each option max 1000 characters.                       |
| `selectionType` | `"single"` \| `"multiple"` | Yes      | Whether voters may choose one or multiple options.                                         |
| `anonymous`     | boolean                    | No       | If `true`, voter identities are hidden. Anonymous polls do not support voting via the API. |

### POST /v2/polls/{pollId}/votes

| Field      | Type   | Required | Description                                                                                 |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `optionId` | string | Yes      | The 6-character ID of the option to vote for. Use the `id` from the poll's `options` array. |

## Constraints

| Constraint                  | Behavior                                                                      |
| --------------------------- | ----------------------------------------------------------------------------- |
| Anonymous polls             | Voting via the API is not supported (`400 anonymous polls are not supported`) |
| Closed polls                | Votes are rejected (`400 poll is closed`)                                     |
| Not a member                | Bot must be a member of the topic (`403`)                                     |
| `selectionType: "single"`   | Each voter can vote for one option                                            |
| `selectionType: "multiple"` | Each voter can vote for any number of options                                 |
| Duplicate votes             | Idempotent — same `{pollId, optionId, voter}` combination is a no-op          |

## Webhook Events

Zenzap fires webhook events when votes are cast or retracted on polls in topics your bot is a member of:

| Event               | Fired when                                                                                   |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `poll_vote.created` | A member votes on a poll                                                                     |
| `poll_vote.deleted` | A vote is retracted (by a user in the app or via `DELETE /v2/polls/{pollId}/votes/{voteId}`) |

See [Webhook Events](/api-reference/webhook-events#poll-vote-events) for full payload details.