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!

What can you do with the Polly API?

API Endpoint
https://api.polly.ai/v1
Terms of Service: https://polly.ai/api/tos
Contact: apiteam@polly.ai
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.create

POST /polls.create

Creates a new single-question Poll.

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']"
  },
  "appeal": "Please take a minute to help our IT Department",
  "anonymity_level": "confidential",
  "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,
    "choices": [
      "Wonderful!",
      "Good",
      "Okay",
      "Poor",
      "Awful"
    ],
    "metadata": {
      "incident_id": "T789DF15-77",
      "incident_number": "#INC100001",
      "phone_number": "775-112-9899",
      "completed_training": false,
      "system_event_id": 61
    }
  }
}
201 Created

The poll was successfully created

401 Unauthorized

Authentication Error

422 Unprocessable Entity

Invalid Parameter Error

429 Too Many Requests

Rate Limit Erorr

500 Internal Server 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",
  "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"
}

/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 deleted

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

The poll was found and returned

401 Unauthorized

Authentication Error

422 Unprocessable Entity

Invalid Parameter Error

429 Too Many Requests

Rate Limit Erorr

500 Internal Server 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",
  "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"
}

/polls.list

POST /polls.list

Returns a list of available polls.

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",
  "metadata": {
    "incident_id": "T178FAQG-1",
    "resolved": true
  }
}
200 OK

The survey was successfully created

401 Unauthorized

Authentication Error

422 Unprocessable Entity

Invalid Parameter Error

429 Too Many Requests

Rate Limit Erorr

500 Internal Server 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",
    "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"
}

/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

The poll was found and deleted.

401 Unauthorized

Authentication Error

422 Unprocessable Entity

Invalid Parameter Error

429 Too Many Requests

Rate Limit Erorr

500 Internal Server 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",
  "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"
}

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.create

POST /surveys.create

Creates a new multi-question Survey.

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']"
  },
  "title": "Employee Onboarding",
  "appeal": "Please take a moment to review your onboarding process",
  "anonymity_level": "confidential",
  "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,
      "choices": [
        "Wonderful!",
        "Good",
        "Okay",
        "Poor",
        "Awful"
      ],
      "metadata": {
        "incident_id": "T789DF15-77",
        "incident_number": "#INC100001",
        "phone_number": "775-112-9899",
        "completed_training": false,
        "system_event_id": 61
      }
    }
  ]
}
201 Created

The survey was successfully created

401 Unauthorized

Authentication Error

422 Unprocessable Entity

Invalid Parameter Error

429 Too Many Requests

Rate Limit Erorr

500 Internal Server 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",
  "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": [
    {
      "type": "multiple_choice",
      "title": "Please rate the service you recieved from our Help Desk!",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "choices": [
        "Wonderful!",
        "Good",
        "Okay",
        "Poor",
        "Awful"
      ],
      "metadata": {
        "incident_id": "T789DF15-77",
        "incident_number": "#INC100001",
        "phone_number": "775-112-9899",
        "completed_training": false,
        "system_event_id": 61
      }
    }
  ]
}
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"
}

/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"
}

The survey was found and returned

401 Unauthorized

Authentication Error

422 Unprocessable Entity

Invalid Parameter Error

429 Too Many Requests

Rate Limit Erorr

500 Internal Server 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",
  "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": [
    {
      "type": "multiple_choice",
      "title": "Please rate the service you recieved from our Help Desk!",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "choices": [
        "Wonderful!",
        "Good",
        "Okay",
        "Poor",
        "Awful"
      ],
      "metadata": {
        "incident_id": "T789DF15-77",
        "incident_number": "#INC100001",
        "phone_number": "775-112-9899",
        "completed_training": false,
        "system_event_id": 61
      }
    }
  ]
}
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"
}

/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

The survey was found and deleted.

401 Unauthorized

Authentication Error

422 Unprocessable Entity

Invalid Parameter Error

429 Too Many Requests

Rate Limit Erorr

500 Internal Server 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",
  "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"
}

/surveys.list

POST /surveys.list

Returns a list of available surveys.

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",
  "metadata": {
    "incident_id": "T178FAQG-1",
    "resolved": true
  }
}

The survey was successfully created

401 Unauthorized

Authentication Error

422 Unprocessable Entity

Invalid Parameter Error

429 Too Many Requests

Rate Limit Erorr

500 Internal Server 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",
    "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": [
      {
        "type": "multiple_choice",
        "title": "Please rate the service you recieved from our Help Desk!",
        "allow_adding_choices": true,
        "allow_multiple_answers": true,
        "choices": [
          "Wonderful!",
          "Good",
          "Okay",
          "Poor",
          "Awful"
        ],
        "metadata": {
          "incident_id": "T789DF15-77",
          "incident_number": "#INC100001",
          "phone_number": "775-112-9899",
          "completed_training": false,
          "system_event_id": 61
        }
      }
    ]
  }
]
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"
}

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.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

422 Unprocessable Entity

Invalid Parameter Error

429 Too Many Requests

Rate Limit Erorr

500 Internal Server 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"
}

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: string public, confidential, anonymous

The level of privacy for votes cast on surveys generated form this template

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": "anonymous",
  "questions": [
    {
      "type": "multiple_choice",
      "title": "Please rate the service you recieved from our Help Desk!",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "choices": [
        "Wonderful!",
        "Good",
        "Okay",
        "Poor",
        "Awful"
      ],
      "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
appeal: string

Additional text to display alongside the Poll question.

anonymity_level: string non_anonymous, confidential, anonymous non_anonymous

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.

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']"
  },
  "appeal": "Please take a minute to help our IT Department",
  "anonymity_level": "confidential",
  "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,
    "choices": [
      "Wonderful!",
      "Good",
      "Okay",
      "Poor",
      "Awful"
    ],
    "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

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",
  "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: string non_anonymous, confidential, anonymous non_anonymous

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.

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",
  "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
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: string non_anonymous, confidential, anonymous non_anonymous

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.

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']"
  },
  "title": "Employee Onboarding",
  "appeal": "Please take a moment to review your onboarding process",
  "anonymity_level": "confidential",
  "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,
      "choices": [
        "Wonderful!",
        "Good",
        "Okay",
        "Poor",
        "Awful"
      ],
      "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: string non_anonymous, confidential, anonymous non_anonymous

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.

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_request
question_request
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",
  "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": [
    {
      "type": "multiple_choice",
      "title": "Please rate the service you recieved from our Help Desk!",
      "allow_adding_choices": true,
      "allow_multiple_answers": true,
      "choices": [
        "Wonderful!",
        "Good",
        "Okay",
        "Poor",
        "Awful"
      ],
      "metadata": {
        "incident_id": "T789DF15-77",
        "incident_number": "#INC100001",
        "phone_number": "775-112-9899",
        "completed_training": false,
        "system_event_id": 61
      }
    }
  ]
}

question_request: object

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

The question being asked

allow_adding_choices: boolean false

Only applies to multiple_choice questions. Allows respondants to add new choices which may be selected as an answer by all other respondants.

allow_multiple_answers: boolean false

Allows respondants to select multiple choices in their poll.

choices: string[]

Only applies to multiple_choice question type. An array of string specifying the different choices for the question.

string
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,
  "choices": [
    "Wonderful!",
    "Good",
    "Okay",
    "Poor",
    "Awful"
  ],
  "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, rank_order
allow_adding_choices: boolean

Only applies to multiple_choice questions. Allows respondants to add new choices which may be selected as an answer by all other respondants.

allow_multiple_answers: boolean

Allows respondants 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 respones 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"
    }
  ]
}

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
}

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"
}