REST API

Use the Team Voice REST API to get, create, update, and delete polls on Jira work items and Confluence pages.

warning

The REST API is still in beta and is subject to change. The request structure was updated on November 28, 2024, due to significant storage changes.

Before using the REST API to access polls, please configure the access token.

GET Get polls for content

Get polls related to content (work items in Jira and pages in Confluence).

Request

Query parameters

• token (required): Your access token
• type (required): polls for getting polls
• workspace (required): Space key in Jira and space ID in Confluence
• content (required): Work item key in Jira and page ID in Confluence
• container (required for Confluence only): Empty in Jira and macro ID in Confluence
• expand (optional): Use the value results to retrieve polls that include calculated results.

Example for Jira version:

note

The REST endpoint URL and access token are unique to your instance. Copy them from the Team Voice settings page after generating an access token.

https://<your-app-id>.hello.atlassian-dev.net/x1/<your-endpoint>?token=<your-access-token>&type=polls&workspace=PLAT&content=PLAT-254604

where:
- 'https://<your-app-id>.hello.atlassian-dev.net/x1/<your-endpoint>' = REST endpoint (copied from Team Voice settings)
- token = <your-access-token>
- type = polls
- workspace = PLAT  (your Jira space key)
- content = PLAT-254604  (your Jira work item key)

Responses

• 200 OK, application/json, Body: Poll[]

Response example

[
    {
        "settings": {
            "allowSelectionOfMultipleOptions": false,
            "resultsVisibility": "alwaysPublic",
            "endDate": "",
            "hideAbsoluteNumbers": false,
            "allowRevote": false,
            "saveParticipantNames": false,
            "closePollOnEndDate": false,
            "allowComment": false
        },
        "options": [
            {
                "id": "1",
                "title": "⭐",
                "order": 0
            },
            {
                "id": "2",
                "title": "⭐⭐",
                "order": 1
            },
            {
                "id": "3",
                "title": "⭐⭐⭐",
                "order": 2
            },
            {
                "id": "4",
                "title": "⭐⭐⭐⭐",
                "order": 3
            },
            {
                "id": "5",
                "title": "⭐⭐⭐⭐⭐",
                "order": 4
            }
        ],
        "description": "Simple scoring from 1 to 5 stars",
        "id": "ee9107b5-5041-4c15-8c76-f14404fa1fad",
        "title": "Stars from ⭐ to ⭐⭐⭐⭐⭐"
    }
]

• 400 Bad request. Required field is not defined in query parameters
• 403 Not permitted. token is not provided or is not valid
• 404 Not found. If pollId is defined, but a poll with this ID is not found

POST Create poll for content

Creates a new poll for defined content.

Request

Query parameters

• token (required): Your access token
• type (required): polls for creating new poll
• workspace (required): Space key in Jira and space ID in Confluence
• content (required): Work item key in Jira and page ID in Confluence
• container (required for Confluence only): Empty in Jira and macro ID in Confluence

Body

Poll

Poll object example

{
  "settings": {
    "allowSelectionOfMultipleOptions": false,
    "resultsVisibility": "alwaysPublic",
    "endDate": "",
    "hideAbsoluteNumbers": false,
    "allowRevote": false,
    "saveParticipantNames": false,
    "closePollOnEndDate": false,
    "allowComment": false
  },
  "options": [
    {
      "id": "1",
      "title": "⭐",
      "order": 0
    },
    {
      "id": "2",
      "title": "⭐⭐",
      "order": 1
    },
    {
        "id": "3",
        "title": "⭐⭐⭐",
        "order": 2
    },
    {
        "id": "4",
        "title": "⭐⭐⭐⭐",
        "order": 3
    },
    {
        "id": "5",
        "title": "⭐⭐⭐⭐⭐",
        "order": 4
    }
  ],
  "description": "Simple scoring from 1 to 5 stars",
  "title": "Stars from ⭐ to ⭐⭐⭐⭐⭐"
}

Responses

• 200 OK, application/json, Body: Poll
• 400 Bad request. Required field is not defined in query parameters
• 403 Not permitted. token is not provided or not valid

PUT Update poll

Update an existing poll in defined content.

Request

Query parameters

• token (required): Your access token
• type (required): polls for updating an existing poll
• workspace (required): Space key in Jira and space ID in Confluence
• content (required): Work item key in Jira and page ID in Confluence
• container (required for Confluence only): Empty in Jira and macro ID in Confluence
• pollId (required): Exact poll ID

Body

Poll

Poll object example

{
  "settings": {
    "allowSelectionOfMultipleOptions": false,
    "resultsVisibility": "alwaysPublic",
    "endDate": "",
    "hideAbsoluteNumbers": false,
    "allowRevote": false,
    "saveParticipantNames": false,
    "closePollOnEndDate": false,
    "allowComment": false
  },
  "options": [
    {
      "id": "1",
      "title": "⭐",
      "order": 0
    },
    {
      "id": "2",
      "title": "⭐⭐",
      "order": 1
    },
    {
        "id": "3",
        "title": "⭐⭐⭐",
        "order": 2
    },
    {
        "id": "4",
        "title": "⭐⭐⭐⭐",
        "order": 3
    },
    {
        "id": "5",
        "title": "⭐⭐⭐⭐⭐",
        "order": 4
    }
  ],
  "description": "Simple scoring from 1 to 5 stars",
  "title": "Stars from ⭐ to ⭐⭐⭐⭐⭐",
  "id": "ee9107b5-5041-4c15-8c76-f14404fa1fad"
}

Responses

• 200 OK, application/json, Body: Poll
• 400 Bad request. Required field is not defined in query parameters
• 403 Not permitted. token is not provided or not valid

DELETE Delete poll

Delete an existing poll in defined content.

Request

Query parameters

• token (required): Your access token
• type (required): polls for deleting an existing poll
• workspace (required): Space key in Jira and space ID in Confluence
• content (required): Work item key in Jira and page ID in Confluence
• container (required for Confluence only): Empty in Jira and macro ID in Confluence
• pollId (required): Exact poll ID

Responses

• 200 OK
• 400 Bad request. Required field is not defined in query parameters for Jira version
• 403 Not permitted. token is not provided or not valid
• 404 Not found. pollId is not found