Polly Web API API Reference

Welcome to the Polly Web API.

The Web API is a great way to query Polly for information and push data into Polly.

Use it for ad-hoc querying of your survey results, or something more complex like sending event driven surveys from external applications!

API Endpoint
https://api.polly.ai/v1
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: 1.0.0

Authentication

APIToken

All requests to the Polly API must specify an authentication token. Tokens can be specified in either the header of the outbound request using the X-API-TOKEN header, or in the body as a parameter called token.

Tokens can be managed at https://app.polly.ai/api

type
apiKey
in
header,body
name
X-API-TOKEN,token
scopes
polls:read

Read poll data

polls:write

Write poll data

surveys:read

Read survey data

surveys:write

Create surveys

workflows:read

Read workflows

workflows:write

Execute workflows

Polls

Poll methods provide access to information and operations related to single question polls. Polls tend to produce less friction for the audience and are a great way to get high level feedback on a simple concept.

Polls

/polls.create

POST /polls.create

Creates a new single-question Poll.

poll_request

Data and options for the poll to be created

Request Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "audience": {
    "user_ids": [
      "UD1SL6ZSP",
      "U3MPANKU4"
    ],
    "emails": [
      "john.doe@example.com",
      "jane.doe@example.com"
    ],
    "channel_names": [
      "#channelname",
      "#otherchannelname"
    ],
    "channel_ids": [
      "C7G7WAHAS",
      "C3SGYMHAG"
    ]
  },
  "alternate_alias": "The HR Team",
  "appeal": "Please take a minute to help our IT Department",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "comments_visibility": "public",
  "send_via_direct_message": false,
  "send_at": "2018-03-27T22:41:28.939Z",
  "close_at": "2018-03-28T22:41:28.939Z",
  "question": {
    "type": "multiple_choice",
    "title": "Please rate the service you recieved from our Help Desk!",
    "allow_adding_choices": true,
    "allow_multiple_answers": true,
    "required": true,
    "allow_comments": true,
    "choices": [
      "Wonderful!",
      "Good",
      "Okay",
      "Poor",
      "Awful"
    ],
    "rank_count": 2,
    "points": 10,
    "metadata": {
      "incident_id": "T789DF15-77",
      "incident_number": "#INC100001",
      "phone_number": "775-112-9899",
      "completed_training": false,
      "system_event_id": 61
    }
  }
}
201 Created
poll_response

The poll was successfully created

type
poll_response
401 Unauthorized
authentication_error

Authentication Error

422 Unprocessable Entity
invalid_parameter_error

Invalid Parameter Error

429 Too Many Requests
rate_limit_error

Rate Limit Erorr

500 Internal Server Error
fatal_error

Fatal Error

Response Example (201 Created) 
{
  "id": "8971234khjasdf987asdfkjnq24",
  "audience": [
    {
      "type": "user",
      "name": "joe@devs.io",
      "channel_id": "U7718512"
    },
    {
      "type": "channel",
      "name": "#random",
      "channel_id": "CH78917"
    }
  ],
  "appeal": "Please take a minute to help our IT Department",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "comments_visibility": "public",
  "send_via_direct_message": false,
  "created_at": "2018-03-27 22:41:28.939Z",
  "send_at": "2018-03-27 22:41:28.939Z",
  "close_at": "2018-03-27 22:41:28.939Z",
  "question": {
    "id": "sBkL6C2BK7aWdwtTF",
    "text": "Rate your Employee Orientation experience.",
    "type": "multiple_choice",
    "allow_adding_choices": true,
    "allow_multiple_answers": true,
    "allow_comments": true,
    "comment_prompt": "Please elaborate on your choice",
    "choices": [
      {
        "index": 0,
        "text": "it was great!"
      },
      {
        "index": 1,
        "text": "it was okay"
      },
      {
        "index": 2,
        "text": "it was bad..."
      }
    ],
    "results": [
      {
        "id": "sBkL6C2BK7aWdwtTF",
        "created_at": "2018-03-27 22:41:28.939Z",
        "user_id": "U7718512",
        "user_name": "Alex",
        "text": "it was ok",
        "choice_id": 1,
        "weight": null,
        "rank": null
      }
    ],
    "comments": [
      {
        "id": "sBkL6C2BK7aWdwtTF",
        "created_at": "2018-03-27 22:41:28.939Z",
        "user_id": "U7718512",
        "user_name": "Alex",
        "text": "I liked the presentation, but I had remaining questions"
      }
    ]
  }
}
Response Example (401 Unauthorized) 
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}
Response Example (422 Unprocessable Entity) 
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}
Response Example (429 Too Many Requests) 
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}
Response Example (500 Internal Server Error) 
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
APIToken polls:write
Polls

/polls.info

POST /polls.info

Returns info about an existing single-question Poll.

This method only needs the id of the poll to be retrieved.

token: token

Authentication token

id: string

ID of the poll to be retrieved

Request Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "id": "8971234khjasdf987asdfkjnq24"
}
200 OK
poll_response

The poll was found and returned

type
poll_response
401 Unauthorized
authentication_error

Authentication Error

422 Unprocessable Entity
invalid_parameter_error

Invalid Parameter Error

429 Too Many Requests
rate_limit_error

Rate Limit Erorr

500 Internal Server Error
fatal_error

Fatal Error

Response Example (200 OK) 
{
  "id": "8971234khjasdf987asdfkjnq24",
  "audience": [
    {
      "type": "user",
      "name": "joe@devs.io",
      "channel_id": "U7718512"
    },
    {
      "type": "channel",
      "name": "#random",
      "channel_id": "CH78917"
    }
  ],
  "appeal": "Please take a minute to help our IT Department",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "comments_visibility": "public",
  "send_via_direct_message": false,
  "created_at": "2018-03-27 22:41:28.939Z",
  "send_at": "2018-03-27 22:41:28.939Z",
  "close_at": "2018-03-27 22:41:28.939Z",
  "question": {
    "id": "sBkL6C2BK7aWdwtTF",
    "text": "Rate your Employee Orientation experience.",
    "type": "multiple_choice",
    "allow_adding_choices": true,
    "allow_multiple_answers": true,
    "allow_comments": true,
    "comment_prompt": "Please elaborate on your choice",
    "choices": [
      {
        "index": 0,
        "text": "it was great!"
      },
      {
        "index": 1,
        "text": "it was okay"
      },
      {
        "index": 2,
        "text": "it was bad..."
      }
    ],
    "results": [
      {
        "id": "sBkL6C2BK7aWdwtTF",
        "created_at": "2018-03-27 22:41:28.939Z",
        "user_id": "U7718512",
        "user_name": "Alex",
        "text": "it was ok",
        "choice_id": 1,
        "weight": null,
        "rank": null
      }
    ],
    "comments": [
      {
        "id": "sBkL6C2BK7aWdwtTF",
        "created_at": "2018-03-27 22:41:28.939Z",
        "user_id": "U7718512",
        "user_name": "Alex",
        "text": "I liked the presentation, but I had remaining questions"
      }
    ]
  }
}
Response Example (401 Unauthorized) 
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}
Response Example (422 Unprocessable Entity) 
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}
Response Example (429 Too Many Requests) 
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}
Response Example (500 Internal Server Error) 
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
APIToken polls:read
Polls

/polls.list

POST /polls.list

Returns a list of available polls.

list_request

Filters for the polls to be retrieved

Request Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "ids": [
    "8971234khjasdf987asdfkjnq24",
    "894khjasdf987asdf1523kjnq24"
  ],
  "author": "U7718512",
  "send_at_from": "2018-03-27 22:41:28.939Z",
  "send_at_to": "2018-05-27 22:41:28.939Z",
  "close_at_from": "2018-03-27 22:41:28.939Z",
  "close_at_to": "2018-05-27 22:41:28.939Z",
  "workflow_id": "YmROkGanp1rQbWB6f",
  "metadata": {
    "incident_id": "T178FAQG-1",
    "resolved": true
  }
}
200 OK
poll_response

The polls were found and returned

type
poll_response
401 Unauthorized
authentication_error

Authentication Error

422 Unprocessable Entity
invalid_parameter_error

Invalid Parameter Error

429 Too Many Requests
rate_limit_error

Rate Limit Erorr

500 Internal Server Error
fatal_error

Fatal Error

Response Example (200 OK) 
[
  {
    "id": "8971234khjasdf987asdfkjnq24",
    "audience": [
      {
        "type": "user",
        "name": "joe@devs.io",
        "channel_id": "U7718512"
      },
      {
        "type": "channel",
        "name": "#random",
        "channel_id": "CH78917"
      }
    ],
    "appeal": "Please take a minute to help our IT Department",
    "anonymity_level": "confidential",
    "results_visibility": "real_time",
    "comments_visibility": "public",
    "send_via_direct_message": false,
    "created_at": "2018-03-27 22:41:28.939Z",
    "send_at": "2018-03-27 22:41:28.939Z",
    "close_at": "2018-03-27 22:41:28.939Z",
    "question": {
      "id": "sBkL6C2BK7aWdwtTF",
      "text": "Rate your Employee Orientation experience.",
      "type": "multiple_choice",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "allow_comments": true,
      "comment_prompt": "Please elaborate on your choice",
      "choices": [
        {
          "index": 0,
          "text": "it was great!"
        },
        {
          "index": 1,
          "text": "it was okay"
        },
        {
          "index": 2,
          "text": "it was bad..."
        }
      ],
      "results": [
        {
          "id": "sBkL6C2BK7aWdwtTF",
          "created_at": "2018-03-27 22:41:28.939Z",
          "user_id": "U7718512",
          "user_name": "Alex",
          "text": "it was ok",
          "choice_id": 1,
          "weight": null,
          "rank": null
        }
      ],
      "comments": [
        {
          "id": "sBkL6C2BK7aWdwtTF",
          "created_at": "2018-03-27 22:41:28.939Z",
          "user_id": "U7718512",
          "user_name": "Alex",
          "text": "I liked the presentation, but I had remaining questions"
        }
      ]
    }
  }
]
Response Example (401 Unauthorized) 
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}
Response Example (422 Unprocessable Entity) 
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}
Response Example (429 Too Many Requests) 
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}
Response Example (500 Internal Server Error) 
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
APIToken polls:read
Polls

/polls.delete

POST /polls.delete

Deletes a poll. This method will delete the poll as well as any associated messages that were delivered. After successful deletion, the poll object is returned to the client.

This method only needs the id of the poll to be deleted.

token: token

Authentication token

id: string

ID of the poll to be deleted

Request Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "id": "8971234khjasdf987asdfkjnq24"
}
200 OK
poll_response

The poll was found and deleted.

type
poll_response
401 Unauthorized
authentication_error

Authentication Error

422 Unprocessable Entity
invalid_parameter_error

Invalid Parameter Error

429 Too Many Requests
rate_limit_error

Rate Limit Erorr

500 Internal Server Error
fatal_error

Fatal Error

Response Example (200 OK) 
{
  "id": "8971234khjasdf987asdfkjnq24",
  "audience": [
    {
      "type": "user",
      "name": "joe@devs.io",
      "channel_id": "U7718512"
    },
    {
      "type": "channel",
      "name": "#random",
      "channel_id": "CH78917"
    }
  ],
  "appeal": "Please take a minute to help our IT Department",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "comments_visibility": "public",
  "send_via_direct_message": false,
  "created_at": "2018-03-27 22:41:28.939Z",
  "send_at": "2018-03-27 22:41:28.939Z",
  "close_at": "2018-03-27 22:41:28.939Z",
  "question": {
    "id": "sBkL6C2BK7aWdwtTF",
    "text": "Rate your Employee Orientation experience.",
    "type": "multiple_choice",
    "allow_adding_choices": true,
    "allow_multiple_answers": true,
    "allow_comments": true,
    "comment_prompt": "Please elaborate on your choice",
    "choices": [
      {
        "index": 0,
        "text": "it was great!"
      },
      {
        "index": 1,
        "text": "it was okay"
      },
      {
        "index": 2,
        "text": "it was bad..."
      }
    ],
    "results": [
      {
        "id": "sBkL6C2BK7aWdwtTF",
        "created_at": "2018-03-27 22:41:28.939Z",
        "user_id": "U7718512",
        "user_name": "Alex",
        "text": "it was ok",
        "choice_id": 1,
        "weight": null,
        "rank": null
      }
    ],
    "comments": [
      {
        "id": "sBkL6C2BK7aWdwtTF",
        "created_at": "2018-03-27 22:41:28.939Z",
        "user_id": "U7718512",
        "user_name": "Alex",
        "text": "I liked the presentation, but I had remaining questions"
      }
    ]
  }
}
Response Example (401 Unauthorized) 
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}
Response Example (422 Unprocessable Entity) 
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}
Response Example (429 Too Many Requests) 
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}
Response Example (500 Internal Server Error) 
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
APIToken polls:write

Surveys

Survey methods provide access to information and operations related to multi-question surveys. Surveys are a great way to hone in on specifics. Data can be cross tabulated and correlated to pull meaningful relationships from the dataset.

Surveys

/surveys.create

POST /surveys.create

Creates a new multi-question Survey.

survey_request

Data and options for the survey to be created

Request Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "audience": {
    "user_ids": [
      "UD1SL6ZSP",
      "U3MPANKU4"
    ],
    "emails": [
      "john.doe@example.com",
      "jane.doe@example.com"
    ],
    "channel_names": [
      "#channelname",
      "#otherchannelname"
    ],
    "channel_ids": [
      "C7G7WAHAS",
      "C3SGYMHAG"
    ]
  },
  "alternate_alias": "The HR Team",
  "title": "Employee Onboarding",
  "appeal": "Please take a moment to review your onboarding process",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "send_via_direct_message": false,
  "send_at": "2018-03-27 22:41:28.939Z",
  "close_at": "2018-03-27 22:41:28.939Z",
  "questions": [
    {
      "type": "multiple_choice",
      "title": "Please rate the service you recieved from our Help Desk!",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "required": true,
      "allow_comments": true,
      "choices": [
        "Wonderful!",
        "Good",
        "Okay",
        "Poor",
        "Awful"
      ],
      "rank_count": 2,
      "points": 10,
      "metadata": {
        "incident_id": "T789DF15-77",
        "incident_number": "#INC100001",
        "phone_number": "775-112-9899",
        "completed_training": false,
        "system_event_id": 61
      }
    }
  ]
}
201 Created
survey_response

The survey was successfully created

type
survey_response
401 Unauthorized
authentication_error

Authentication Error

422 Unprocessable Entity
invalid_parameter_error

Invalid Parameter Error

429 Too Many Requests
rate_limit_error

Rate Limit Erorr

500 Internal Server Error
fatal_error

Fatal Error

Response Example (201 Created) 
{
  "id": "sBkL6C2BK7aWdwtTF",
  "audience": [
    {
      "type": "user",
      "name": "joe@devs.io",
      "channel_id": "U7718512"
    },
    {
      "type": "channel",
      "name": "#random",
      "channel_id": "CH78917"
    }
  ],
  "title": "Employee Onboarding",
  "appeal": "Please take a moment to review your onboarding process",
  "author_id": "U2GTQ5RRD",
  "author_name": "kayleefrye",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "comments_visibility": "public",
  "send_via_direct_message": false,
  "created_at": "2018-08-16T23:15:41.303Z",
  "send_at": "2018-08-16T23:15:41.303Z",
  "close_at": "2018-08-16T23:15:41.303Z",
  "questions": [
    {
      "id": "sBkL6C2BK7aWdwtTF",
      "text": "Rate your Employee Orientation experience.",
      "type": "multiple_choice",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "allow_comments": true,
      "comment_prompt": "Please elaborate on your choice",
      "choices": [
        {
          "index": 0,
          "text": "it was great!"
        },
        {
          "index": 1,
          "text": "it was okay"
        },
        {
          "index": 2,
          "text": "it was bad..."
        }
      ],
      "results": [
        {
          "id": "sBkL6C2BK7aWdwtTF",
          "created_at": "2018-03-27 22:41:28.939Z",
          "user_id": "U7718512",
          "user_name": "Alex",
          "text": "it was ok",
          "choice_id": 1,
          "weight": null,
          "rank": null
        }
      ],
      "comments": [
        {
          "id": "sBkL6C2BK7aWdwtTF",
          "created_at": "2018-03-27 22:41:28.939Z",
          "user_id": "U7718512",
          "user_name": "Alex",
          "text": "I liked the presentation, but I had remaining questions"
        }
      ]
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}
Response Example (422 Unprocessable Entity) 
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}
Response Example (429 Too Many Requests) 
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}
Response Example (500 Internal Server Error) 
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
APIToken surveys:write
Surveys

/surveys.info

POST /surveys.info

Queries and returns a single survey that matches the provided id.

id of the survey to be returned

token: token

Authentication token

id: string

ID of the survey to be returned

Request Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "id": "sBkL6C2BK7aWdwtTF"
}
200 OK
survey_response

The survey was found and returned

type
survey_response
401 Unauthorized
authentication_error

Authentication Error

422 Unprocessable Entity
invalid_parameter_error

Invalid Parameter Error

429 Too Many Requests
rate_limit_error

Rate Limit Erorr

500 Internal Server Error
fatal_error

Fatal Error

Response Example (200 OK) 
{
  "id": "sBkL6C2BK7aWdwtTF",
  "audience": [
    {
      "type": "user",
      "name": "joe@devs.io",
      "channel_id": "U7718512"
    },
    {
      "type": "channel",
      "name": "#random",
      "channel_id": "CH78917"
    }
  ],
  "title": "Employee Onboarding",
  "appeal": "Please take a moment to review your onboarding process",
  "author_id": "U2GTQ5RRD",
  "author_name": "kayleefrye",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "comments_visibility": "public",
  "send_via_direct_message": false,
  "created_at": "2018-08-16T23:15:41.303Z",
  "send_at": "2018-08-16T23:15:41.303Z",
  "close_at": "2018-08-16T23:15:41.303Z",
  "questions": [
    {
      "id": "sBkL6C2BK7aWdwtTF",
      "text": "Rate your Employee Orientation experience.",
      "type": "multiple_choice",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "allow_comments": true,
      "comment_prompt": "Please elaborate on your choice",
      "choices": [
        {
          "index": 0,
          "text": "it was great!"
        },
        {
          "index": 1,
          "text": "it was okay"
        },
        {
          "index": 2,
          "text": "it was bad..."
        }
      ],
      "results": [
        {
          "id": "sBkL6C2BK7aWdwtTF",
          "created_at": "2018-03-27 22:41:28.939Z",
          "user_id": "U7718512",
          "user_name": "Alex",
          "text": "it was ok",
          "choice_id": 1,
          "weight": null,
          "rank": null
        }
      ],
      "comments": [
        {
          "id": "sBkL6C2BK7aWdwtTF",
          "created_at": "2018-03-27 22:41:28.939Z",
          "user_id": "U7718512",
          "user_name": "Alex",
          "text": "I liked the presentation, but I had remaining questions"
        }
      ]
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}
Response Example (422 Unprocessable Entity) 
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}
Response Example (429 Too Many Requests) 
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}
Response Example (500 Internal Server Error) 
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
APIToken surveys:read
Surveys

/surveys.delete

POST /surveys.delete

Deletes a survey. This method will delete the survey as well as any associated messages that were delivered. After successful deletion, the survey object is returned to the client.

This method only needs the id of the survey to be deleted.

token: token

Authentication token

id: string

ID of the survey to be deleted

Request Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "id": "sBkL6C2BK7aWdwtTF"
}
200 OK
survey_response

The survey was found and deleted.

type
survey_response
401 Unauthorized
authentication_error

Authentication Error

422 Unprocessable Entity
invalid_parameter_error

Invalid Parameter Error

429 Too Many Requests
rate_limit_error

Rate Limit Erorr

500 Internal Server Error
fatal_error

Fatal Error

Response Example (200 OK) 
{
  "id": "sBkL6C2BK7aWdwtTF",
  "audience": [
    {
      "type": "user",
      "name": "joe@devs.io",
      "channel_id": "U7718512"
    },
    {
      "type": "channel",
      "name": "#random",
      "channel_id": "CH78917"
    }
  ],
  "title": "Employee Onboarding",
  "appeal": "Please take a moment to review your onboarding process",
  "author_id": "U2GTQ5RRD",
  "author_name": "kayleefrye",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "comments_visibility": "public",
  "send_via_direct_message": false,
  "created_at": "2018-08-16T23:15:41.303Z",
  "send_at": "2018-08-16T23:15:41.303Z",
  "close_at": "2018-08-16T23:15:41.303Z",
  "questions": [
    {
      "id": "sBkL6C2BK7aWdwtTF",
      "text": "Rate your Employee Orientation experience.",
      "type": "multiple_choice",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "allow_comments": true,
      "comment_prompt": "Please elaborate on your choice",
      "choices": [
        {
          "index": 0,
          "text": "it was great!"
        },
        {
          "index": 1,
          "text": "it was okay"
        },
        {
          "index": 2,
          "text": "it was bad..."
        }
      ],
      "results": [
        {
          "id": "sBkL6C2BK7aWdwtTF",
          "created_at": "2018-03-27 22:41:28.939Z",
          "user_id": "U7718512",
          "user_name": "Alex",
          "text": "it was ok",
          "choice_id": 1,
          "weight": null,
          "rank": null
        }
      ],
      "comments": [
        {
          "id": "sBkL6C2BK7aWdwtTF",
          "created_at": "2018-03-27 22:41:28.939Z",
          "user_id": "U7718512",
          "user_name": "Alex",
          "text": "I liked the presentation, but I had remaining questions"
        }
      ]
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}
Response Example (422 Unprocessable Entity) 
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}
Response Example (429 Too Many Requests) 
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}
Response Example (500 Internal Server Error) 
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
APIToken surveys:write
Surveys

/surveys.list

POST /surveys.list

Returns a list of available surveys.

list_request

Filters for the surveys to be retrieved

Request Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "ids": [
    "8971234khjasdf987asdfkjnq24",
    "894khjasdf987asdf1523kjnq24"
  ],
  "author": "U7718512",
  "send_at_from": "2018-03-27 22:41:28.939Z",
  "send_at_to": "2018-05-27 22:41:28.939Z",
  "close_at_from": "2018-03-27 22:41:28.939Z",
  "close_at_to": "2018-05-27 22:41:28.939Z",
  "workflow_id": "YmROkGanp1rQbWB6f",
  "metadata": {
    "incident_id": "T178FAQG-1",
    "resolved": true
  }
}
200 OK
survey_response

The surveys were found and returned

type
survey_response
401 Unauthorized
authentication_error

Authentication Error

422 Unprocessable Entity
invalid_parameter_error

Invalid Parameter Error

429 Too Many Requests
rate_limit_error

Rate Limit Erorr

500 Internal Server Error
fatal_error

Fatal Error

Response Example (200 OK) 
[
  {
    "id": "sBkL6C2BK7aWdwtTF",
    "audience": [
      {
        "type": "user",
        "name": "joe@devs.io",
        "channel_id": "U7718512"
      },
      {
        "type": "channel",
        "name": "#random",
        "channel_id": "CH78917"
      }
    ],
    "title": "Employee Onboarding",
    "appeal": "Please take a moment to review your onboarding process",
    "author_id": "U2GTQ5RRD",
    "author_name": "kayleefrye",
    "anonymity_level": "confidential",
    "results_visibility": "real_time",
    "comments_visibility": "public",
    "send_via_direct_message": false,
    "created_at": "2018-08-16T23:15:41.303Z",
    "send_at": "2018-08-16T23:15:41.303Z",
    "close_at": "2018-08-16T23:15:41.303Z",
    "questions": [
      {
        "id": "sBkL6C2BK7aWdwtTF",
        "text": "Rate your Employee Orientation experience.",
        "type": "multiple_choice",
        "allow_adding_choices": true,
        "allow_multiple_answers": true,
        "allow_comments": true,
        "comment_prompt": "Please elaborate on your choice",
        "choices": [
          {
            "index": 0,
            "text": "it was great!"
          },
          {
            "index": 1,
            "text": "it was okay"
          },
          {
            "index": 2,
            "text": "it was bad..."
          }
        ],
        "results": [
          {
            "id": "sBkL6C2BK7aWdwtTF",
            "created_at": "2018-03-27 22:41:28.939Z",
            "user_id": "U7718512",
            "user_name": "Alex",
            "text": "it was ok",
            "choice_id": 1,
            "weight": null,
            "rank": null
          }
        ],
        "comments": [
          {
            "id": "sBkL6C2BK7aWdwtTF",
            "created_at": "2018-03-27 22:41:28.939Z",
            "user_id": "U7718512",
            "user_name": "Alex",
            "text": "I liked the presentation, but I had remaining questions"
          }
        ]
      }
    ]
  }
]
Response Example (401 Unauthorized) 
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}
Response Example (422 Unprocessable Entity) 
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}
Response Example (429 Too Many Requests) 
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}
Response Example (500 Internal Server Error) 
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
APIToken surveys:read

Templates

Template methods provide access to information and operations related to templates and library. Templates are saved surveys that can be reused.

Workflows

Workflow methods provide access to Polly's automated workflow system. You can configure a series of polls or surveys to send to an audience. They are a great way to easily build feedback systems around things like product rollouts, employee happiness, sprint retrospectives, and help desk satisfaction. Through the api, you can push external data along with your polls and surveys, allowing for powerful cross-system feedback integrations!

Workflows

/workflows.trigger

POST /workflows.trigger

Kicks off a workflow and attaches any data sent in metadata to each poll or survey that gets sent as a result. The configured surveys and polls will send based on your configuration in the web app. You can configure the parameters that you will be pushing in as the metadata attribute in the request body on the workflow authoring page.

id: string

id of the workflow to trigger

metadata: metadata
Request Example
{
  "id": "sBkL6C2BK7aWdwtTF",
  "metadata": {
    "incident_id": "T789DF15-77",
    "incident_number": "#INC100001",
    "phone_number": "775-112-9899",
    "completed_training": false,
    "system_event_id": 61
  }
}
200 OK

The workflow was triggered successfully

type
object
401 Unauthorized
authentication_error

Authentication Error

422 Unprocessable Entity
invalid_parameter_error

Invalid Parameter Error

429 Too Many Requests
rate_limit_error

Rate Limit Erorr

500 Internal Server Error
fatal_error

Fatal Error

Response Example (200 OK) 
{
  "id": "sBkL6C2BK7aWdwtTF",
  "title": "IT Incident Resolution Satisfaction",
  "actions": [
    {
      "id": "eRoL4G1AF3aWdrtYN",
      "type": "poll",
      "title": "Incident Reporter Follow-up",
      "scheduled_for": "2018-10-19T12:00:00.000Z",
      "audience": [
        {
          "type": "user",
          "name": "user@mail.com",
          "channel_id": "D7FK19R3G"
        }
      ]
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}
Response Example (422 Unprocessable Entity) 
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}
Response Example (429 Too Many Requests) 
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}
Response Example (500 Internal Server Error) 
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
APIToken workflows:write
Workflows

/workflows.results

POST /workflows.results

Returns a list of results associated with a workflow.

token: token
id: string

id of the workflow to return results for

created_at_from: object

Datetime string in ISODate format. Lower bound of created at date, inclusive

created_at_to: object

Datetime string in ISODate format. Upper bound of created at date, inclusive

Request Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "id": "sBkL6C2BK7aWdwtTF",
  "created_at_from": "2018-03-27 22:41:28.939Z",
  "created_at_to": "2018-05-27 22:41:28.939Z"
}
200 OK
workflow_results_response

The results were successfully found and returned

401 Unauthorized
authentication_error

Authentication Error

422 Unprocessable Entity
invalid_parameter_error

Invalid Parameter Error

429 Too Many Requests
rate_limit_error

Rate Limit Erorr

500 Internal Server Error
fatal_error

Fatal Error

Response Example (200 OK) 
{
  "workflow_id": "pYrufLstS78zbRAFf",
  "results": [
    {
      "poll_id": "2v8vYWdxNFoPmo7Bk",
      "survey_id": "Z4WmdAw5Knj4bN2vN",
      "question_id": "8aXkDdqfuWusLBPGv",
      "vote": {
        "id": "sBkL6C2BK7aWdwtTF",
        "created_at": "2018-03-27 22:41:28.939Z",
        "user_id": "U7718512",
        "user_name": "Alex",
        "text": "it was ok",
        "choice_id": 1,
        "weight": null,
        "rank": null
      }
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}
Response Example (422 Unprocessable Entity) 
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}
Response Example (429 Too Many Requests) 
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}
Response Example (500 Internal Server Error) 
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
APIToken workflows:read

Schema Definitions

Template: object

id: string

Unique ID

createdAt: string

Datetime string in ISO 8601 format

title: string

A short title for the template

description: string

A short description of the template

appeal: string

A message to include in alongside surveys generated from this template

anonymity: anonymity_level
questions: question_request
question_request
Example
{
  "id": "sBkL6C2BK7aWdwtTF",
  "createdAt": "2018-03-27T22:41:28.939Z",
  "title": "Employee Onboarding",
  "description": "Survey for new employees after orientation",
  "appeal": "Please take a moment to help us improve our onboarding process!",
  "anonymity": "confidential",
  "questions": [
    {
      "type": "multiple_choice",
      "title": "Please rate the service you recieved from our Help Desk!",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "required": true,
      "allow_comments": true,
      "choices": [
        "Wonderful!",
        "Good",
        "Okay",
        "Poor",
        "Awful"
      ],
      "rank_count": 2,
      "points": 10,
      "metadata": {
        "incident_id": "T789DF15-77",
        "incident_number": "#INC100001",
        "phone_number": "775-112-9899",
        "completed_training": false,
        "system_event_id": 61
      }
    }
  ]
}

audience_response_info: array

The audience for the poll. These values may any combination of slack channel names (e.g. #general), channel ids (e.g. CH78917G), email addresses, or slack ids (e.g. U7718612). If one or more emails or slack ids are provided, the poll will send via direct message.

object
type: string user, channel
name: string
channel_id: string
Example
[
  {
    "type": "user",
    "name": "joe@devs.io",
    "channel_id": "U7718512"
  },
  {
    "type": "channel",
    "name": "#random",
    "channel_id": "CH78917"
  }
]

poll_request: object

token: token
audience: audience
alternate_alias: string

Adds an alias to represent which team or system is initiating the poll.

appeal: string

Additional text to display alongside the Poll question.

anonymity_level: anonymity_level
results_visibility: results_visibility
comments_visibility: comments_visibility
send_via_direct_message: boolean false

Sends the poll to the audience via direct message.

send_at: dateTime now

Sends the poll at this time. If no value is provided, the poll will send immediately

close_at: dateTime send_at + 7 days

Closes the poll at this time. If no value is provided, the poll will close in 7 days after send at time.

question: question_request
Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "audience": {
    "user_ids": [
      "UD1SL6ZSP",
      "U3MPANKU4"
    ],
    "emails": [
      "john.doe@example.com",
      "jane.doe@example.com"
    ],
    "channel_names": [
      "#channelname",
      "#otherchannelname"
    ],
    "channel_ids": [
      "C7G7WAHAS",
      "C3SGYMHAG"
    ]
  },
  "alternate_alias": "The HR Team",
  "appeal": "Please take a minute to help our IT Department",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "comments_visibility": "public",
  "send_via_direct_message": false,
  "send_at": "2018-03-27T22:41:28.939Z",
  "close_at": "2018-03-28T22:41:28.939Z",
  "question": {
    "type": "multiple_choice",
    "title": "Please rate the service you recieved from our Help Desk!",
    "allow_adding_choices": true,
    "allow_multiple_answers": true,
    "required": true,
    "allow_comments": true,
    "choices": [
      "Wonderful!",
      "Good",
      "Okay",
      "Poor",
      "Awful"
    ],
    "rank_count": 2,
    "points": 10,
    "metadata": {
      "incident_id": "T789DF15-77",
      "incident_number": "#INC100001",
      "phone_number": "775-112-9899",
      "completed_training": false,
      "system_event_id": 61
    }
  }
}

list_request: object

token: token
ids: string[]

Array of ids that should be included

string
author: string

Filter requested objects to those created by this author. Use slack id for user

send_at_from: object

Datetime string in ISODate format. Lower bound of send date, inclusive

send_at_to: object

Datetime string in ISODate format. Upper bound of send date, inclusive

close_at_from: object

Datetime string in ISODate format. Lower bound of close date, inclusive

close_at_to: object

Datetime string in ISODate format. Upper bound of close date, inclusive

workflow_id: object

Optionally allows filtering using the id of a single workflow

metadata: object

Searches for custom key value pairs that were added to a poll or survey though an api call or through a workflow event trigger. Metadata allows you to push extra data into a poll or survey for the purpose of querying it later or associating it with external systems, data, or events. The keys of this object are set when you call polls.create or surveys.create with a metadata object included in the request body. This object is may have values that are string, number, boolean or string[]

Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "ids": [
    "8971234khjasdf987asdfkjnq24",
    "894khjasdf987asdf1523kjnq24"
  ],
  "author": "U7718512",
  "send_at_from": "2018-03-27 22:41:28.939Z",
  "send_at_to": "2018-05-27 22:41:28.939Z",
  "close_at_from": "2018-03-27 22:41:28.939Z",
  "close_at_to": "2018-05-27 22:41:28.939Z",
  "workflow_id": "YmROkGanp1rQbWB6f",
  "metadata": {
    "incident_id": "T178FAQG-1",
    "resolved": true
  }
}

poll_response: object

id: string

UUID of the a poll

audience: audience_response_info
appeal: string

Additional text to display alongside the Poll question.

anonymity_level: anonymity_level
results_visibility: results_visibility
comments_visibility: comments_visibility
send_via_direct_message: boolean

Sends the poll to the audience via direct message.

created_at: object now

Datetime string in ISODate format. The time a poll was created

send_at: object now

Datetime string in ISODate format. Sends the poll at this time. If no value is provided, the poll will send immediately

close_at: object

Datetime string in ISODate format. Closes the poll at this time. If no value is provided, the poll will close in 7 days.

question: question_response
Example
{
  "id": "8971234khjasdf987asdfkjnq24",
  "audience": [
    {
      "type": "user",
      "name": "joe@devs.io",
      "channel_id": "U7718512"
    },
    {
      "type": "channel",
      "name": "#random",
      "channel_id": "CH78917"
    }
  ],
  "appeal": "Please take a minute to help our IT Department",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "comments_visibility": "public",
  "send_via_direct_message": false,
  "created_at": "2018-03-27 22:41:28.939Z",
  "send_at": "2018-03-27 22:41:28.939Z",
  "close_at": "2018-03-27 22:41:28.939Z",
  "question": {
    "id": "sBkL6C2BK7aWdwtTF",
    "text": "Rate your Employee Orientation experience.",
    "type": "multiple_choice",
    "allow_adding_choices": true,
    "allow_multiple_answers": true,
    "allow_comments": true,
    "comment_prompt": "Please elaborate on your choice",
    "choices": [
      {
        "index": 0,
        "text": "it was great!"
      },
      {
        "index": 1,
        "text": "it was okay"
      },
      {
        "index": 2,
        "text": "it was bad..."
      }
    ],
    "results": [
      {
        "id": "sBkL6C2BK7aWdwtTF",
        "created_at": "2018-03-27 22:41:28.939Z",
        "user_id": "U7718512",
        "user_name": "Alex",
        "text": "it was ok",
        "choice_id": 1,
        "weight": null,
        "rank": null
      }
    ],
    "comments": [
      {
        "id": "sBkL6C2BK7aWdwtTF",
        "created_at": "2018-03-27 22:41:28.939Z",
        "user_id": "U7718512",
        "user_name": "Alex",
        "text": "I liked the presentation, but I had remaining questions"
      }
    ]
  }
}

survey_request: object

token: token
audience: audience
alternate_alias: string

Adds an alias to represent which team or system is initiating the survey.

title: string

Title for the survey. This text will be prominently displayed at the top of the survey.

appeal: string

Additional text that is shown below the survey title.

anonymity_level: anonymity_level
results_visibility: results_visibility
send_via_direct_message: boolean false

If set to true the survey sends an initial notification to the audience via direct message. If set to false, the initial notification will be posted in the specified channels.

send_at: object now

Datetime string in ISODate format. Sends the poll at this time. If no value is provided, the poll will send immediately

close_at: object

Datetime string in ISODate format. Closes the poll at this time. If no value is provided, the poll will close in 7 days.

questions: question_request
question_request
Example
{
  "token": "xob-hadsf7hj1234njhasdfkj1jfhasdko",
  "audience": {
    "user_ids": [
      "UD1SL6ZSP",
      "U3MPANKU4"
    ],
    "emails": [
      "john.doe@example.com",
      "jane.doe@example.com"
    ],
    "channel_names": [
      "#channelname",
      "#otherchannelname"
    ],
    "channel_ids": [
      "C7G7WAHAS",
      "C3SGYMHAG"
    ]
  },
  "alternate_alias": "The HR Team",
  "title": "Employee Onboarding",
  "appeal": "Please take a moment to review your onboarding process",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "send_via_direct_message": false,
  "send_at": "2018-03-27 22:41:28.939Z",
  "close_at": "2018-03-27 22:41:28.939Z",
  "questions": [
    {
      "type": "multiple_choice",
      "title": "Please rate the service you recieved from our Help Desk!",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "required": true,
      "allow_comments": true,
      "choices": [
        "Wonderful!",
        "Good",
        "Okay",
        "Poor",
        "Awful"
      ],
      "rank_count": 2,
      "points": 10,
      "metadata": {
        "incident_id": "T789DF15-77",
        "incident_number": "#INC100001",
        "phone_number": "775-112-9899",
        "completed_training": false,
        "system_event_id": 61
      }
    }
  ]
}

survey_response: object

id: string

Unique ID

audience: audience_response_info
title: string

Title for the survey. This text will be prominently displayed at the top of the survey.

appeal: string

Additional text that is shown below the survey title.

author_id: string

Slack ID of the survey's author

author_name: string

Slack username of the survey's author

anonymity_level: anonymity_level
results_visibility: results_visibility
comments_visibility: comments_visibility
send_via_direct_message: boolean false

If set to true the survey sends an initial notification to the audience via direct message. If set to false, the initial notification will be posted in the specified channels.

created_at: object

The time at which the survey was created.

send_at: object

The time at which the survey is scheduled to send.

close_at: object

The time at which the survey closes. The message will update for audience members that have not take the survey to show that it is closed and no responses will be allowed after this time.

questions: question_response
question_response
Example
{
  "id": "sBkL6C2BK7aWdwtTF",
  "audience": [
    {
      "type": "user",
      "name": "joe@devs.io",
      "channel_id": "U7718512"
    },
    {
      "type": "channel",
      "name": "#random",
      "channel_id": "CH78917"
    }
  ],
  "title": "Employee Onboarding",
  "appeal": "Please take a moment to review your onboarding process",
  "author_id": "U2GTQ5RRD",
  "author_name": "kayleefrye",
  "anonymity_level": "confidential",
  "results_visibility": "real_time",
  "comments_visibility": "public",
  "send_via_direct_message": false,
  "created_at": "2018-08-16T23:15:41.303Z",
  "send_at": "2018-08-16T23:15:41.303Z",
  "close_at": "2018-08-16T23:15:41.303Z",
  "questions": [
    {
      "id": "sBkL6C2BK7aWdwtTF",
      "text": "Rate your Employee Orientation experience.",
      "type": "multiple_choice",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "allow_comments": true,
      "comment_prompt": "Please elaborate on your choice",
      "choices": [
        {
          "index": 0,
          "text": "it was great!"
        },
        {
          "index": 1,
          "text": "it was okay"
        },
        {
          "index": 2,
          "text": "it was bad..."
        }
      ],
      "results": [
        {
          "id": "sBkL6C2BK7aWdwtTF",
          "created_at": "2018-03-27 22:41:28.939Z",
          "user_id": "U7718512",
          "user_name": "Alex",
          "text": "it was ok",
          "choice_id": 1,
          "weight": null,
          "rank": null
        }
      ],
      "comments": [
        {
          "id": "sBkL6C2BK7aWdwtTF",
          "created_at": "2018-03-27 22:41:28.939Z",
          "user_id": "U7718512",
          "user_name": "Alex",
          "text": "I liked the presentation, but I had remaining questions"
        }
      ]
    }
  ]
}

question_request: object

type: string 1_to_5, 1_to_10, agree_disagree, multiple_choice, nps, open_ended, point_allocation, ranked
title: string

The question being asked

allow_adding_choices: boolean false

Only applies to multiple_choice questions, and only if it's a single question poll. Allows respondents to add new choices which may be selected as an answer by all other respondents.

allow_multiple_answers: boolean false

Only allowed for multiple_choice questions. Allows respondents to select multiple choices in their poll.

required: boolean false

Only applies to survey questions. Determines if the question is required in order to submit a response.

allow_comments: boolean false

Only allowed for multiple_choice questions. Allow respondents to add comments to a question.

choices: string[]

Only applies to the multiple_choice, ranked, and point_allocation question types. An array of string specifying the different choices for the question.

string
rank_count: integer 2 ≤ x ≤ 5

Required if question type is ranked, inapplicable otherwise. The number of options respondents are to rank (e.g. 2 if you want them to rank their top two choices)

points: integer 2 ≤ x ≤ 100

Required if question type is point_allocation, inapplicable otherwise. The total number of points each respondent can allocate to the options.

metadata: metadata
Example
{
  "type": "multiple_choice",
  "title": "Please rate the service you recieved from our Help Desk!",
  "allow_adding_choices": true,
  "allow_multiple_answers": true,
  "required": true,
  "allow_comments": true,
  "choices": [
    "Wonderful!",
    "Good",
    "Okay",
    "Poor",
    "Awful"
  ],
  "rank_count": 2,
  "points": 10,
  "metadata": {
    "incident_id": "T789DF15-77",
    "incident_number": "#INC100001",
    "phone_number": "775-112-9899",
    "completed_training": false,
    "system_event_id": 61
  }
}

question_response: object

id: string

Unique ID

text: string

Text of the question

type: string 1_to_5, 1_to_10, agree_disagree, multiple_choice, nps, open_ended, point_allocation, ranked
allow_adding_choices: boolean

Only applies to multiple_choice questions, and only if it's a single question poll. Allows respondents to add new choices which may be selected as an answer by all other respondents.

allow_multiple_answers: boolean

Allows respondents to select multiple choices in their poll.

allow_comments: boolean

Allows a respondent to leave a comment about their response

comment_prompt: string

Text that displays in the 'Leave comment' menu. Only relevant if allow_comments=true

choices: choice

Array of choices. Only for multiple-choice question types.

choice
results: vote

Array of responses to the question

vote
comments: comment

Array of comments for this question

comment
Example
{
  "id": "sBkL6C2BK7aWdwtTF",
  "text": "Rate your Employee Orientation experience.",
  "type": "multiple_choice",
  "allow_adding_choices": true,
  "allow_multiple_answers": true,
  "allow_comments": true,
  "comment_prompt": "Please elaborate on your choice",
  "choices": [
    {
      "index": 0,
      "text": "it was great!"
    },
    {
      "index": 1,
      "text": "it was okay"
    },
    {
      "index": 2,
      "text": "it was bad..."
    }
  ],
  "results": [
    {
      "id": "sBkL6C2BK7aWdwtTF",
      "created_at": "2018-03-27 22:41:28.939Z",
      "user_id": "U7718512",
      "user_name": "Alex",
      "text": "it was ok",
      "choice_id": 1,
      "weight": null,
      "rank": null
    }
  ],
  "comments": [
    {
      "id": "sBkL6C2BK7aWdwtTF",
      "created_at": "2018-03-27 22:41:28.939Z",
      "user_id": "U7718512",
      "user_name": "Alex",
      "text": "I liked the presentation, but I had remaining questions"
    }
  ]
}

workflow_results_response: object

workflow_id: string

Id of the workflow that results are for

results: object[]
object
poll_id: string

Id of the poll that the result is for

survey_id: string

Id of the survey that the result is for

question_id: string

Id of the question that the result is for

vote: vote
Example
{
  "workflow_id": "pYrufLstS78zbRAFf",
  "results": [
    {
      "poll_id": "2v8vYWdxNFoPmo7Bk",
      "survey_id": "Z4WmdAw5Knj4bN2vN",
      "question_id": "8aXkDdqfuWusLBPGv",
      "vote": {
        "id": "sBkL6C2BK7aWdwtTF",
        "created_at": "2018-03-27 22:41:28.939Z",
        "user_id": "U7718512",
        "user_name": "Alex",
        "text": "it was ok",
        "choice_id": 1,
        "weight": null,
        "rank": null
      }
    }
  ]
}

metadata: object

Additional data to include with every poll or survey sent as a result of this workflow being triggered. This is a good way to push in external event data such as an incident_id, external_email, or other data that gives the polls / surveys context from the event that triggered them. The metadata object must be a single depth object with values

string
boolean
number
null
string[]
string
Example
{
  "incident_id": "T789DF15-77",
  "incident_number": "#INC100001",
  "phone_number": "775-112-9899",
  "completed_training": false,
  "system_event_id": 61
}

choice: object

id: number

This ID is unique among other choices in a given poll or survey. The ID also specifies the order in which the choices are displayed to the audience.

text: string

Text displayed for the option of a multiple choice question

votes: number

The number of votes cast for this choice. In the case of point_allocation questions, this is the total points given to this option.

Example
{
  "id": "0",
  "text": "It was great!",
  "votes": "number"
}

vote: object

id: string

Unique ID

created_at: object now

Datetime string in ISODate format. The time a vote was made

user_id: string

The slack-designated id of the user who cast the vote, null if the vote was anonymous

user_name: string

The name of the user who cast the vote, null if the vote was anonymous

text: string

The text value of the option this vote corresponds to

choice_id: number

The ID of the selected

weight: number

Only applies to Point Allocation and Ranked Choice questions, the amount of points assigned to this vote

rank: number

Only applies to Ranked Choice questions, the selected rank assigned to this option

Example
{
  "id": "sBkL6C2BK7aWdwtTF",
  "created_at": "2018-03-27 22:41:28.939Z",
  "user_id": "U7718512",
  "user_name": "Alex",
  "text": "it was ok",
  "choice_id": 1,
  "weight": null,
  "rank": null
}

anonymity_level: string

non_anonymous identifies the user for each vote. confidential does not identify the user, but allows data to be used with filters and demographic data. anonymous does not identify voters in any way. anonymizeParticipantResults does not identify users in results but does identify them to the author

string non_anonymous, confidential, anonymous, anonymize_particpant_results non_anonymous

results_visibility: string

Whether and when results will be visible to the audience: real_time means results will be available from the start, on_close means results will be shown when the poll or survey closes, hidden means they will not be visible to the audience at all.

string real_time, on_close, hidden real_time

comments_visibility: string

Whether or not comments should be visible to the participants

string hidden, public hidden

comment: object

id: string

Unique ID

created_at: object now

Datetime string in ISODate format. The time a comment was made

user_id: string

The slack-designated id of the user who posted the comment, or null if the comment was anonymous

user_name: string

The name of the user who cast the vote, or an anonymized placeholder if the comment was anonymous

text: string

The text value of the comment

Example
{
  "id": "sBkL6C2BK7aWdwtTF",
  "created_at": "2018-03-27 22:41:28.939Z",
  "user_id": "U7718512",
  "user_name": "Alex",
  "text": "I liked the presentation, but I had remaining questions"
}

audience: object

user_ids: string[]

A string array of slack-designated user IDs

string
emails: string[]

A string array of user email addresses

string
channel_names: string[]

An array of slack team channels

string
channel_ids: string[]

An array of slack-designated team channel IDs

string
Example
{
  "user_ids": [
    "UD1SL6ZSP",
    "U3MPANKU4"
  ],
  "emails": [
    "john.doe@example.com",
    "jane.doe@example.com"
  ],
  "channel_names": [
    "#channelname",
    "#otherchannelname"
  ],
  "channel_ids": [
    "C7G7WAHAS",
    "C3SGYMHAG"
  ]
}

token: string

Polly API Authentication token

authentication_error: object

An authentication error occured. Either the token was not provided in the header or body, or was not valid

Example
{
  "type": "authentication_error",
  "message": "Authentication rejected"
}

rate_limit_error: object

The token has made too many requests recently and has been rate limited. The response includes a wait_until property which specifies when requests will be accepted again. Any requests before that time can increase the time needed to wait.

type: string
wait_until: string
message: string
Example
{
  "type": "rate_limit_error",
  "wait_until": "2019-04-23T18:25:43.511Z",
  "message": "Too many requests. Wait until 2019-04-23T18:25:43.511Z"
}

invalid_request_error: object

The formation of the request is invalid. This occurs when the request itself is unprocessable, usually due to invalid json formatting.

type: string
message: string
Example
{
  "type": "invalid_request_error",
  "message": "Your request was unprocessable. Request body must be JSON formatted data. Please check the request formatting and try again."
}

invalid_parameter_error: object

type: string
message: string
validation_errors: object[]
object
parameter: string

The name of the invalid parameter

reason: string

The reason the value is invalid. Note there can be many failures per parameter.

value: string

The value of the parameter that is invalid

Example
{
  "type": "invalid_parameter_error",
  "message": "Your request contained invalid parameters",
  "validation_errors": [
    {
      "parameter": "audience[2]",
      "reason": "Must be channel name, email address, channel id, or slack id",
      "value": "John Doe"
    },
    {
      "parameter": "question.title",
      "reason": "Required"
    }
  ]
}

missing_scope_error: object

The provided token does not have the authorization scopes required to perform this action.

type: string
message: string
required: string[]

List of scopes required to complete the request.

string
provided: string[]

List of scopes that have been granted to the token.

string
Example
{
  "type": "missing_scope_error",
  "message": "The provided token does not have the authorization scopes required to perform this action.",
  "required": [
    "polls:read",
    "polls:write",
    "templates:write"
  ],
  "provided": [
    "polls:read",
    "templates:write"
  ]
}

permission_error: object

This occurs when the provided token has appropriate scopes for the request but does not have access to the specific data which was requested. For example, if a request is made to read the results of a poll to which the token does not have access, a permission_error will be returned.

type: string
message: string
Example
{
  "type": "permission_error",
  "message": "This token does not have access to the requested data"
}

fatal_error: object

An error occurred on our end from which we were not able to recover. Please try the request again or contact our api support at apiteam@polly.ai.

type: string
message: string
Example
{
  "type": "fatal_error",
  "message": "An internal server error occurred"
}
Documentation by Spectacle