> ## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.