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! 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 Write poll data Read survey data Execute workflows 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. Creates a new single-question Poll. Data and options for the poll to be created The poll was successfully created Authentication Error Invalid Parameter Error Rate Limit Erorr Returns info about an existing single-question Poll. This method only needs the id of the poll to be retrieved. Authentication token ID of the poll to be retrieved The poll was found and returned Authentication Error Invalid Parameter Error Rate Limit Erorr Returns a list of available polls. Filters for the polls to be retrieved The polls were found and returned Authentication Error Invalid Parameter Error Rate Limit Erorr 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. Authentication token ID of the poll to be deleted The poll was found and deleted. Authentication Error Invalid Parameter Error Rate Limit Erorr 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.create Creates a new multi-question Survey. Data and options for the survey to be created The survey was successfully created Authentication Error Invalid Parameter Error Rate Limit Erorr Queries and returns a single survey that matches the provided id. id of the survey to be returned Authentication token ID of the survey to be returned The survey was found and returned Authentication Error Invalid Parameter Error Rate Limit Erorr /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. Authentication token ID of the survey to be deleted The survey was found and deleted. Authentication Error Invalid Parameter Error Rate Limit Erorr Returns a list of available surveys. Filters for the surveys to be retrieved The surveys were found and returned Authentication Error Invalid Parameter Error Rate Limit Erorr 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.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 of the workflow to trigger The workflow was triggered successfully Authentication Error Invalid Parameter Error Rate Limit Erorr /workflows.results Returns a list of results associated with a workflow. id of the workflow to return results for Datetime string in ISODate format. Lower bound of created at date, inclusive Datetime string in ISODate format. Upper bound of created at date, inclusive The results were successfully found and returned Authentication Error Invalid Parameter Error Rate Limit Erorr 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. reminders: object Configuration for sending reminders. Total number of reminders to send. Must be a maximum of 10. Interval between reminders. Unit of time for the reminder interval. Accepted values are minutes, hours, days, weeks. poll_request: object Adds an alias to represent which team or system is initiating the poll. Additional text to display alongside the Poll question. Sends the poll to the audience via direct message. Sends the poll at this time. If no value is provided, the poll will send immediately Closes the poll at this time. If no value is provided, the poll will close in 7 days after send at time. list_request: object Array of ids that should be included Filter requested objects to those created by this author. Use slack id for user

Datetime string in ISODate format. Lower bound of send date, inclusive Datetime string in ISODate format. Upper bound of send date, inclusive Datetime string in ISODate format. Lower bound of close date, inclusive Datetime string in ISODate format. Upper bound of close date, inclusive Optionally allows filtering using the id of a single workflow 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[] poll_response: object UUID of the a poll Additional text to display alongside the Poll question. Whether the poll is currently active. Set to false if the poll is closed. Sends the poll to the audience via direct message. Datetime string in ISODate format. The time a poll was created Datetime string in ISODate format. Sends the poll at this time. If no value is provided, the poll will send immediately Datetime string in ISODate format. Closes the poll at this time. If no value is provided, the poll will close in 7 days. survey_request: object Adds an alias to represent which team or system is initiating the survey. Title for the survey. This text will be prominently displayed at the top of the survey. Additional text that is shown below the survey title. 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. Datetime string in ISODate format. Sends the poll at this time. If no value is provided, the poll will send immediately Datetime string in ISODate format. Closes the poll at this time. If no value is provided, the poll will close in 7 days. survey_response: object Title for the survey. This text will be prominently displayed at the top of the survey. Additional text that is shown below the survey title. Whether the survey is currently active. Set to false if the survey is closed. Slack ID of the survey's author Slack username of the survey's author 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. The time at which the survey was created. The time at which the survey is scheduled to send. 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. question_request: object The question being asked 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. Only allowed for multiple_choice questions. Allows respondents to select multiple choices in their poll. Only applies to survey questions. Determines if the question is required in order to submit a response. Only allowed for multiple_choice questions. Allow respondents to add comments to a question. Only applies to the multiple_choice, ranked, and point_allocation question types. An array of string specifying the different choices for the question. 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) Required if question type is point_allocation, inapplicable otherwise. The total number of points each respondent can allocate to the options. question_response: object Text of the question 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. Allows respondents to select multiple choices in their poll. Allows a respondent to leave a comment about their response Text that displays in the 'Leave comment' menu. Only relevant if allow_comments=true Array of choices. Only for multiple-choice question types. Array of responses to the question Array of comments for this question workflow_results_response: object Id of the workflow that results are for Id of the poll that the result is for Id of the survey that the result is for Id of the question that the result is for 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 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 displayed for the option of a multiple choice question The number of votes cast for this choice. In the case of point_allocation questions, this is the total points given to this option. Datetime string in ISODate format. The time a vote was made The slack-designated id of the user who cast the vote, null if the vote was anonymous The name of the user who cast the vote, null if the vote was anonymous The text value of the option this vote corresponds to The ID of the selected Only applies to Point Allocation and Ranked Choice questions, the amount of points assigned to this vote Only applies to Ranked Choice questions, the selected rank assigned to this option 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 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. comments_visibility: string Whether or not comments should be visible to the participants comment: object Datetime string in ISODate format. The time a comment was made The slack-designated id of the user who posted the comment, or null if the comment was anonymous The name of the user who cast the vote, or an anonymized placeholder if the comment was anonymous The text value of the comment audience: object A string array of slack-designated user IDs A string array of user email addresses An array of slack team channels An array of slack-designated team channel IDs 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 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. 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. invalid_parameter_error: object The name of the invalid parameter The reason the value is invalid. Note there can be many failures per parameter. The value of the parameter that is invalid missing_scope_error: object The provided token does not have the authorization scopes required to perform this action. List of scopes required to complete the request. List of scopes that have been granted to the token. 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. 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 .