Poll

GET/api/v1/polls

List_polls

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Conditions as filter[][]=. Conditions on different fields all apply. in (any of) and all (every one of, on fields holding several values) take a comma-separated list (\, for a literal comma). exists takes true or false. Datetimes are RFC 3339, now, or a time before now such as -30m, -6h or -7d.

q?string

Full-text search over this list's searchable fields.

Length1 <= length <= 200

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: title, option_count, total_ballots, opens_at, closes_at, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/polls"

{  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "polls": [    {      "_relations": {        "property1": {          "has_more": true,          "returned": 0,          "total": 0        },        "property2": {          "has_more": true,          "returned": 0,          "total": 0        }      },      "ballots_visibility": "private",      "before_close": "aggregate_only",      "closes_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "created_by": "string",      "description": "string",      "identity_guard": {        "allow_change_vote": true,        "kind": "jwt_sub"      },      "live_stream_enabled": true,      "max_selections": 0,      "metadata": null,      "on_close": "freeze_results",      "opens_at": "2019-08-24T14:15:22Z",      "option_count": 0,      "options": [        {          "description": "string",          "label": "string",          "option_id": "string",          "poll_id": "string",          "position": 0,          "status": "active",          "write_in": true        }      ],      "poll_id": "string",      "quorum": null,      "results_visibility": "public",      "status": "draft",      "strategy": "single_choice",      "title": "string",      "total_ballots": 0,      "updated_at": "2019-08-24T14:15:22Z",      "weighting": {        "currency_id": "string",        "domain": "string",        "kind": "none",        "max_weight": 0,        "scale": 0,        "snapshot": true,        "static_weight": 0      },      "write_ins_enabled": true    }  ]}

POST/api/v1/polls

Create_poll

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

closes_at?|

When the poll closes

Formatdate-time

description?|

Optional description

identity_guard?null|

live_stream_enabled?boolean

Whether to enable a live result stream

max_selections?|

Maximum selections allowed for multi-select polls (defaults to 1)

Formatint32

Range0 <= value

opens_at?|

When the poll opens

Formatdate-time

options*array<string>

Option labels

quorum_min_agents?|

Minimum number of distinct voters (agents) required for quorum

Formatint64

Range0 <= value

quorum_required?|

Required ballot count for quorum

Formatint64

Range0 <= value

strategy?null|

title*string

Poll title / question

visibility?null|

weighting?null|

write_ins_enabled?boolean

Whether write-in options are accepted

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/polls" \  -H "Content-Type: application/json" \  -d '{    "options": [      "string"    ],    "title": "string"  }'

{  "created_at": "2019-08-24T14:15:22Z",  "options": [    {      "id": "string",      "label": "string"    }  ],  "poll_id": "string",  "status": "draft"}

GET/api/v1/polls/{poll_id}

Get_poll

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

poll_id*string

Query Parameters

include?string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/polls/string"

{  "_relations": {    "property1": {      "has_more": true,      "returned": 0,      "total": 0    },    "property2": {      "has_more": true,      "returned": 0,      "total": 0    }  },  "ballots_visibility": "private",  "before_close": "aggregate_only",  "closes_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "description": "string",  "identity_guard": {    "allow_change_vote": true,    "kind": "jwt_sub"  },  "live_stream_enabled": true,  "max_selections": 0,  "metadata": null,  "on_close": "freeze_results",  "opens_at": "2019-08-24T14:15:22Z",  "option_count": 0,  "options": [    {      "description": "string",      "label": "string",      "option_id": "string",      "poll_id": "string",      "position": 0,      "status": "active",      "write_in": true    }  ],  "poll_id": "string",  "quorum": null,  "results_visibility": "public",  "status": "draft",  "strategy": "single_choice",  "title": "string",  "total_ballots": 0,  "updated_at": "2019-08-24T14:15:22Z",  "weighting": {    "currency_id": "string",    "domain": "string",    "kind": "none",    "max_weight": 0,    "scale": 0,    "snapshot": true,    "static_weight": 0  },  "write_ins_enabled": true}

GET/api/v1/polls/{poll_id}/ballot

Get_ballot

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

poll_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/polls/string/ballot"

{  "ballot_id": "string",  "poll_id": "string",  "receipt": {    "accepted_at": "2019-08-24T14:15:22Z",    "ballot_hash": "string"  },  "selections": [    {      "option_id": "string",      "rank": 0,      "weight": 0    }  ],  "write_in": "string"}

POST/api/v1/polls/{poll_id}/close

Close_poll

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

poll_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/polls/string/close"

{  "poll_id": "string",  "status": "draft",  "total_ballots": 0}

POST/api/v1/polls/{poll_id}/finalize

Finalize_poll

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

poll_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/polls/string/finalize"

{  "poll_id": "string",  "quorum_met": true,  "status": "draft",  "total_ballots": 0}

POST/api/v1/polls/{poll_id}/options

Add_option

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

poll_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

description?|

Optional option description

label*string

Option label

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/polls/string/options" \  -H "Content-Type: application/json" \  -d '{    "label": "string"  }'

{  "label": "string",  "option_id": "string",  "poll_id": "string",  "position": 0}

GET/api/v1/polls/{poll_id}/results

Get_results

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

poll_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/polls/string/results"

{  "irv_rounds": [    {      "counts": {        "property1": 0,        "property2": 0      },      "eliminated": "string",      "round": 0    }  ],  "options": [    {      "label": "string",      "option_id": "string",      "votes": 0,      "weighted_votes": 0    }  ],  "poll_id": "string",  "quorum": null,  "status": "draft",  "strategy": "single_choice",  "total_ballots": 0,  "updated_at": "2019-08-24T14:15:22Z",  "winner": "string"}

GET/api/v1/polls/{poll_id}/stream

Stream_poll

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

poll_id*string

Query Parameters

token?string

JWT token (alternative to the Authorization header for browser clients)

Response Body

curl -X GET "https://example.com/api/v1/polls/string/stream"

Empty

POST/api/v1/polls/{poll_id}/vote

Vote

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

poll_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

option?|

Single option id (single-choice / yes-no)

options?array<string>

Multiple option ids (multi-select)

ranked?array<string>

Ordered option ids (ranked-choice)

write_in?|

Write-in text

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/polls/string/vote" \  -H "Content-Type: application/json" \  -d '{}'

{  "accepted": true,  "ballot_id": "string",  "poll_id": "string",  "receipt": {    "accepted_at": "2019-08-24T14:15:22Z",    "ballot_hash": "string"  }}

200application/json

400

503

201application/json

400

403

503

200application/json

404

503

200application/json

403

404

503

200application/json

403

404

409

503

200application/json

403

404

409

503

201application/json

403

404

409

503

200application/json

403

404

503

101

401

404

202application/json

400

404

409

503

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`