Create a unique poll.

  • A choice poll is created by default with the datePoll parameter value as false.

  • An event poll is created if the datePoll parameter value is set to true.

  • A poll can be created even if you provide the mandatory parameters only. The default values for the optional parameters, if any, are then used.

  • All mandatory parameters are validated. Depending on the incorrect or missing data, error messages are generated. See Validations.

  • The response returns code 200 if the poll creation was successful else error messages are generated. See Error codes.

The operation uses basic authentication.

Resource URL

POST method on <ConfluenceBaseURL>/rest/polls/1.0/poll

ConfluenceBaseURL is the URL of your Confluence instance.


See Parameters to learn more about the required and optional parameters of both choice and event polls.

Quick reference (Parameter name - default value, if any; mandatory fields are marked with *)

name *



datePoll - false (true to create event poll)

nonUserVotesAllowed - false

pollAnonymous - false

votersVisible - true

resultsBeforeClosed - true

undoAllowed - true

multipleChoice - false

optionsExtendable - false

tinyUrlEnabled - false

percentsVisible - true (available for choice poll only)

voteCountVisible - true

options *

stringValue (* for choice poll & at least two values are required)

dateValue (* for event poll & at least one value is required)

Format to be used for options:

Choice poll

Event poll


{ "stringValue": "choice1" },
{ "stringValue": "choice2" }



{"dateValue":"2022-05-19", "stringValue": "1"},

{"dateValue":"2022-05-20", "stringValue": "2"}


Example request

Sample request payload to create a choice poll

"name": "Choice poll - What product do you like best?",
"description": "Choose the product you like most",
"datePoll": false,
"nonUserVotesAllowed": false,
"pollAnonymous": false,
"votersVisible": true,
"percentsVisible": true,
"votesCountVisible": true,
"resultsBeforeClosed": true,
"undoAllowed": true,
"multipleChoice": false,
"optionsExtendable": false,
"tinyUrlEnabled": false,
"options": [
{ "stringValue": "choice1" },
{ "stringValue": "choice2" }
"closedAt": "2022-03-19"

Sample request payload to create an event poll

"name": "Event Poll- Select the meeting time for conference",
"description": "Choose the time for meeting ?",
"datePoll": true,
"multipleChoice": true,
"pollAnonymous": false,
"votersVisible": true,
"nonUserVotesAllowed": false,
"resultsBeforeClosed": true,
"undoAllowed": true,
"tinyUrlEnabled": false,
"optionsExtendable": false,
"options": [
{ "dateValue": "date1","stringValue":"1AM" },
{ "dateValue": "date2"}
"closedAt": "2022-03-19"

Example response

Sample response after successful execution of request

"result": "ok",
"guid": "7cf62f8135c1455888bf13e1dd125e5b",
"status": "200"


Validation condition

Validated parameter name(s)



If poll name is missing in the request payload


  • For choice poll: “Please fill in a question.”

  • For event poll: “Please fill in the name of the event.”

Poll name is mandatory to create polls.

If poll options are missing in the request payload

  • options

  • dateValue (in case of event poll)

  • For choice poll: “Please provide at least two choices.”

  • For event poll: “Please provide at least one date.”

  • For choice polls, at least two choices must be provided.

  • For event poll, at lease one date must be given.

Data validation

  • name

  • description

  • enddate

  • stringValue (in case of choice poll)

  • Poll name and description should be less than 1024 characters.

  • Poll descriptions should be less than 255 characters.

  • Choice poll option should be less than 255 characters.

  • End date should not be less than current date.

Error codes


Cause of error

Message displayed


Validation errors as mentioned in the above table. See Validations.


User is not permitted to perform a particular operation.

Operation failed with error not allowed.


Invalid user credentials.

Operation failed with error unauthorized.