Navbar
shell
  • Introduction
  • Authentication
  • Good To Know
  • API Endpoints
  • All Element Types
  • Webhooks
  • Webhooks Endpoints
  • Errors
  • Feedback and Support



  • Introduction

    Main API endpoint

    https://api.surveyhero.com/v1/
    

    The SurveyHero API is REST-based and can be accessed with the use of API keys. Responses will always be in JSON format. This documentation will guide you through authentication and present all different endpoints that can be consumed.

    Authentication

    Creating API keys

    Before you can start using the API, you will need to create a secret API key. To do this, please visit the "Developer API" section in your SurveyHero account.

    Your API key will provide you with a username and a password. These credentials are required to perform "Basic Authentication" and obtain access to your data via this API.

    Throughout this documentation we will show code examples containing username:password. Please always replace username and password with your actual credentials.

    Managing API keys

    You can create multiple API keys and name them individually. This allows you to use one key per service, e.g. one key for your WordPress plugin and one for your cronjob server. In case of a compromise of one of those services, you will be able to only deactivate or delete the affected key, without disrupting your remaining services.

    You can deactivate or delete an API key at any time in your account. API access to your data will be revoked immediately. The difference between "deactivating" and "deleting" is that deleting is permanent while a deactivated key can be reactivated.

    How to authenticate

    Example request

    # Make sure to replace 'username' and 'password' with your actual credentials
    curl -X GET "https://api.surveyhero.com/v1/" \
         -u "username:password"
    

    Authentication is done via "Basic Auth" (HTTP authentication), that requires a username and a password. The credentials are concatenated with a trailing colon (username:password) and then encoded using a Base64 algorithm. This encoded value (e.g. dXNlcm5hbWU6cGFzc3dvcmQ=) is then added to the request header:

    Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

    Most programming languages and libraries provide built-in "Basic Auth" support that does automatically add the request header above. We recommend that you check first whether such an implementation already exists, before implementing your own.

    Good To Know

    Responses

    Example response

    {
      "surveys": []
    }
    

    All responses are UTF-8 encoded and in JSON format. Responses will always return an object literal as main object, and never simply an array or a boolean, etc.

    Timestamp

    Example timestamp format

    {
      "created_on": "2017-08-07T12:07:56+0000"
    }
    

    All timestamps are formatted based on ISO 8601. All timestamps are shown in UTC.

    Rate Limiting

    Please do not make more than two requests per second. Making a new request less than 500ms after the last request will immediately fail and return a "Too Many Requests" error.

    API Endpoints

    Get all surveys

    Example request

    curl -X GET "https://api.surveyhero.com/v1/surveys" \
         -u "username:password"
    

    Example response

    {
      "surveys": [
        {
          "survey_id": 1000,
          "title": "Customer Satisfaction Survey",
          "created_on": "2017-08-07T12:07:56+0000",
          "number_of_questions": 12,
          "number_of_responses": 78
        },
        {
          "survey_id": 53635,
          "title": "Event Feedback",
          "created_on": "2018-02-27T20:12:33+0000",
          "number_of_questions": 3,
          "number_of_responses": 2
        }
      ]
    }
    

    This endpoint returns all surveys that you have access to. These are your own surveys as well as surveys shared with you from team members.

    HTTP request

    GET https://api.surveyhero.com/v1/surveys

    Response properties

    Property surveys will contain an array with your surveys, sorted by survey title in alphabetical order.

    Property Type Description
    survey_id integer Unique identifier for the survey.
    title string Title of the survey.
    created_on timestamp Timestamp of when the survey was created.
    number_of_questions integer Number of questions contained in survey. This does only contain actual questions, not static text or other elements.
    number_of_responses integer Total number of responses collected with survey.

    Get survey details

    Example request

    curl -X GET "https://api.surveyhero.com/v1/surveys/1001" \
         -u "username:password"
    

    Example response

    {
      "survey_id": 53635,
      "title": "Event Feedback",
      "created_on": "2018-02-27T20:12:33+0000",
      "number_of_elements": 6,
      "number_of_questions": 3,
      "number_of_responses": 2,
      "number_of_webhooks": 1,
      "settings": {
        "is_anonymous": false,
        "is_active": true
      }
    }
    

    You can get more general details about a survey. This endpoint is normally the entry point for accessing its questions, responses, etc.

    HTTP request

    GET https://api.surveyhero.com/v1/surveys/{survey_id}

    Response properties

    Property Type Description
    survey_id integer Unique identifier for the survey.
    title string Title of the survey.
    created_on timestamp Timestamp of when the survey was created.
    number_of_elements integer Total number of elements contained in the survey. This includes all questions as well as static elements, such as text, images, etc.
    number_of_questions integer Number of actual questions in the survey.
    number_of_responses integer Total number of responses collected with survey.
    number_of_webhooks integer Total number of webhooks that have been set for this survey.
    settings.is_anonymous boolean Whether it is an anonymous survey.
    settings.is_active boolean Value is true if at least one active collector exists.

    Get all elements from survey

    Example request

    curl -X GET "https://api.surveyhero.com/v1/surveys/53635/elements" \
         -u "username:password"
    

    Example response

    {
      "elements": [
        {
          "element_id": 664789,
          "element_type": "static_title",
          "text": "Event Feedback"
        },
        {
          "element_id": 664697,
          "element_type": "net_promoter_score",
          "question_text": "How likely is it that you would recommend the event to a friend or colleague?",
          "description_text": "",
          "properties": {
            "left_text": "Not at all likely",
            "right_text": "Extremely likely"
          },
          "validations": {
              "is_required": false
          }
        },
        {
          "element_id": 664706,
          "element_type": "multi_line_text_input",
          "question_text": "Is there anything you would like to share about the event?",
          "description_text": "",
          "properties": {
            "text_before_input": "",
            "text_after_input": "",
            "default_value": ""
          },
          "validations": {
            "is_required": false,
            "max_number_of_characters": null
          }
        }
      ]
    }
    

    As well as a variety of question types, a survey may also contain "helper" content such as text paragraphs, titles, images, etc. The overall term for all these is "elements". An element can therefore be a question or just static content. This endpoint will return each and every element within your survey.

    If you are only interested in the actual questions within your survey, you can also fetch questions only.

    HTTP request

    GET https://api.surveyhero.com/v1/surveys/{survey_id}/elements

    Response properties

    Property elements will contain an array with all elements contained in the survey. They are ordered according to their position in the live survey. While each element type will have specific properties, they do all share following properties:

    Property Type Description
    element_id integer Unique identifier for the element.
    element_type string Element type name. Each element type has different properties.

    Get only questions from survey

    Example request

    curl -X GET "https://api.surveyhero.com/v1/surveys/53635/questions" \
         -u "username:password"
    

    Example response

    {
      "elements": [
        {
          "element_id": 664697,
          "element_type": "net_promoter_score",
          "question_text": "How likely is it that you would recommend the event to a friend or colleague?",
          "description_text": "",
          "properties": {
            "left_text": "Not at all likely",
            "right_text": "Extremely likely"
          },
          "validations": {
              "is_required": false
          }
        },
        {
          "element_id": 664706,
          "element_type": "multi_line_text_input",
          "question_text": "Is there anything you would like to share about the event?",
          "description_text": "",
          "properties": {
            "text_before_input": "",
            "text_after_input": "",
            "default_value": ""
          },
          "validations": {
            "is_required": false,
            "max_number_of_characters": null
          }
        }
      ]
    }
    

    Compared to fetching all elements, this endpoint will only return the question elements contained in the survey. Knowing the details about the questions within your survey will help you to understand the answer data from your respondents.

    HTTP request

    GET https://api.surveyhero.com/v1/surveys/{survey_id}/questions

    Response properties

    Property elements will contain an array with all questions contained in the survey, in the same order as they appear in the questionnaire. While each element type will have specific properties, all questions share following properties:

    Property Type Description
    question_text string Question text.
    description_text string Additional text below question text.
    properties object Various properties based on element type.
    validations object Various properties based on element type. One property that all questions do share is is_required (bool).
    validations.is_required boolean This property is shared among all question elements. If true, a participant cannot submit their answers without answering this question.

    Get all responses

    Example request

    curl -X GET "https://api.surveyhero.com/v1/surveys/53635/responses" \
         -u "username:password"
    

    Example response

    {
      "responses": [
        {
          "response_id": 3863473,
          "started_on": "2018-02-27T20:14:29+0000",
          "last_updated_on": "2018-02-27T20:16:06+0000",
          "email_address": null,
          "link_parameters": {
            "client-id": 12345,
            "company": "Acme Inc."
          },
          "ip_address": null,
          "meta_data": {
            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.186 Safari/537.36"
          },
          "status": "completed"
        },
        {
          "response_id": 3863469,
          "started_on": "2018-02-27T20:13:59+0000",
          "last_updated_on": "2018-02-27T20:14:27+0000",
          "email_address": null,
          "link_parameters": {},
          "ip_address": null,
          "meta_data": {
            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.186 Safari/537.36"
          },
          "status": "incomplete"
        }
      ]
    }
    

    With this endpoint you will get an overview of all responses given to your survey. Whenever someone participates in a survey, this generates a response. If you need to get the actual answers given within a response, you can simply access its response_id.

    HTTP request

    GET https://api.surveyhero.com/v1/surveys/{survey_id}/responses

    Response properties

    Property responses will contain an array with all responses given to your survey, in ascending order (newest first).

    Property Type Description
    response_id integer Unique identifier for the response.
    started_on timestamp Timestamp of when the participant has opened your survey for the first time.
    last_updated_on timestamp Timestamp of the last time the user navigated through your survey or submitted their answers (clicked "Back", "Next" or "Finish"). If the status of this response is completed, then last_updated_on represents the time of completion.
    email_address string|null If the respondent was invited using our "Email Invite" collector, their email address will show here. However, if you have set your survey to be "anonymous", this value will always be null.
    link_parameters object Any GET parameters that were added to the survey link of the participant will show here. However, if you have set your survey to be "anonymous", this value will always be empty.
    ip_address string|null If the collector was set to save IP addresses, they will show here. However, if you have set your survey to be "anonymous", this value will always be null.
    meta_data object Browser meta data are being saved with each participation and shown here.
    status string Participation status can either be incomplete or completed. Incomplete means that the participant has started, but not yet finished the survey. If last_updated_on is a long time ago, it might be a drop-off.

    Get all answers from response

    Example request

    curl -X GET "https://api.surveyhero.com/v1/surveys/53635/responses/3863469" \
         -u "username:password"
    

    Example response

    {
      "response_id": 3863469,
      "started_on": "2018-02-27T20:13:59+0000",
      "last_updated_on": "2018-02-28T11:15:13+0000",
      "email_address": null,
      "link_parameters": {},
      "ip_address": null,
      "meta_data": {
        "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.186 Safari/537.36"
      },
      "status": "incomplete",
      "previous_response_id": null,
      "next_response_id": 3863473,
      "answers": [
        {
          "element_id": 666812,
          "element_type": "multi_line_text_input",
          "question_text": "Do you have any further comments?",
          "answer": {
            "type": "text",
            "value": "Everything was nicely organized, thank you!"
          }
        },
        {
          "element_id": 664697,
          "element_type": "net_promoter_score",
          "question_text": "How likely is it that you would recommend the event to a friend or colleague?",
          "answer": {
            "type": "number",
            "number": 9
          }
        },
        {
          "element_id": 666809,
          "element_type": "drop_down",
          "question_text": "In which department do you work?",
          "answer": {
            "type": "choices",
            "value": [
              {
                "choice_id": 1745223,
                "text": "Department B"
              }
            ]
          }
        }
      ]
    }
    

    This endpoint allows you to retrieve all answers given within a response.

    HTTP request

    GET https://api.surveyhero.com/v1/surveys/{survey_id}/responses/{response_id}

    Response properties

    The object will contain the same properties as in the responses overview, with following addition:

    Property Type Description
    previous_response_id integer|null Unique identifier of the previous response. If null, then there is no previous response meaning this is the first available response.
    next_response_id integer|null Unique identifier of the next response. If null, then there is no next response meaning this is the last available response.
    answers object[] Array with one answer object per question in your survey.
    answers[].element_id integer Unique identifier of the corresponding question within your survey. You can find all details about the question by looking up the question details.
    answers[].element_type string Element type name. Each element type has different properties.
    answers[].question_text string Question text.
    answers[].answer object Will contain the answers given to the corresponding question.
    answers[].answer.type string The type of the answer. May either be a simple type such as text or number, or a more complex type such as choices, ranking, etc. This might be different for each question type. A list of available types can be found below.
    answers[].answer.value any Will contain the answer data, structured according to its type.

    Available answer types

    An answer object always consists of a type and a value. The data of value is structured according to its type. Following types exist: text, number, date, file, choices, ranking, choice_table, input_table

    The data structure for the different answer types and values can be found with each individual question type.

    All Element Types

    We support many different element types and since each one is different, they all have their own properties and formats. In this section you can learn about the structure and options of each element type.

    Single-line text input

    Example element data

    {
      "element_id": 666811,
      "element_type": "single_line_text_input",
      "question_text": "What is your full name?",
      "description_text": "",
      "properties": {
        "text_before_input": "",
        "text_after_input": "",
        "default_value": ""
      },
      "validations": {
        "is_required": false,
        "max_number_of_characters": null
      }
    }
    

    Example response data

    {
      "element_id": 666811,
      "element_type": "single_line_text_input",
      "question_text": "What is your full name?",
      "answer": {
        "type": "text",
        "value": "John Smith"
      }
    }
    

    Example of a single-line text input question

    Element properties

    Property Type Description
    properties.text_before_input string Additional text added before the text input.
    properties.text_after_input string Additional text added after the text input.
    properties.default_value string Default value in the text input.
    validations.max_number_of_characters number|null Limited number of characters a participant can type as answer.

    Answer properties

    Property Type Description
    answer.type string Available types: text
    answer.value string|null Text answer of participant. null if no answer was given.

    Multi-line text input

    Example element data

    {
      "element_id": 666812,
      "element_type": "multi_line_text_input",
      "question_text": "Do you have any further comments?",
      "description_text": "Please feel free to leave us a note here.",
      "properties": {
        "default_value": ""
      },
      "validations": {
        "is_required": false,
        "max_number_of_characters": 500
      }
    }
    

    Example response data

    {
      "element_id": 666812,
      "element_type": "multi_line_text_input",
      "question_text": "Do you have any further comments?",
      "answer": {
        "type": "text",
        "value": "Everything was nicely organized, thank you!"
      }
    }
    

    Example of a multi-line text input question

    Element properties

    Property Type Description
    properties.default_value string Default value in the text area.
    validations.max_number_of_characters number|null Limited number of characters a participant can type as answer.

    Answer properties

    Property Type Description
    answer.type string Available types: text
    answer.value string|null Text answer of participant. null if no answer was given.

    Example element data

    {
      "element_id": 666809,
      "element_type": "drop_down",
      "question_text": "In which department do you work?",
      "description_text": "",
      "properties": {
        "choices": [
          {
            "choice_id": 1745222,
            "text": "Department A"
          },
          {
            "choice_id": 1745223,
            "text": "Department B"
          },
          {
            "choice_id": 1745224,
            "text": "Department C"
          }
        ]
      },
      "validations": {
        "is_required": true
      }
    }
    

    Example response data

    {
      "element_id": 666809,
      "element_type": "drop_down",
      "question_text": "In which department do you work?",
      "answer": {
        "type": "choices",
        "value": [
          {
            "choice_id": 1745223,
            "text": "Department B"
          }
        ]
      }
    }
    

    Example of a drop-down question

    Element properties

    Property Type Description
    properties.choices object[] Array with one object per available choice within drop-down list.
    properties.choices[].choice_id integer Unique identifier of the choice.
    properties.choices[].text string Choice text visible to the participant.

    Answer properties

    Property Type Description
    answer.type string Available types: choices
    answer.value object[] Array of choices, listing choices selected by participant.

    Multiple choice

    Example element data

    {
      "element_id": 666967,
      "element_type": "multiple_choice",
      "question_text": "Which of these courses have you already attended?",
      "description_text": "You can select multiple options.",
      "properties": {
        "choices": [
          {
            "choice_id": 1745870,
            "text": "Course A"
          },
          {
            "choice_id": 1745871,
            "text": "Course B"
          },
          {
            "choice_id": 1745872,
            "text": "Course C"
          },
          {
            "choice_id": 1745873,
            "text": "Course D"
          },
          {
            "choice_id": 0,
            "text": "Other"
          }
        ]
      },
      "validations": {
        "is_required": false,
        "allow_multiple_choices": true,
        "min_number_of_choices": null,
        "max_number_of_choices": null
      }
    }
    

    Example response data

    {
      "element_id": 666967,
      "element_type": "multiple_choice",
      "question_text": "Which of these courses have you already attended?",
      "answer": {
        "type": "choices",
        "value": [
          {
            "choice_id": 1745870,
            "text": "Course A"
          },
          {
            "choice_id": 1745872,
            "text": "Course C"
          },
          {
            "choice_id": 0,
            "text": "I think it was Course E"
          }
        ]
      }
    }
    

    Example of a multiple choice question

    Element properties

    Property Type Description
    properties.choices object[] Array with one object per available choice within multiple choice question.
    properties.choices[].choice_id integer Unique identifier of the choice.
    properties.choices[].text string Choice text visible to the participant.
    validations.allow_multiple_choices boolean Whether the multiple choice question allows multiple selections or only one.
    validations.min_number_of_choices integer|null Minimum number of choices a participant must make. Will always be null if allow_multiple_choicesisfalse`.
    validations.max_number_of_choices integer|null Maximum number of choices a participant can make. Will always be null if allow_multiple_choicesisfalse`.

    Answer properties

    Property Type Description
    answer.type string Available types: choices
    answer.value object[] Array of choices, listing choices selected by participant. If choice_id equals 0, then the selected choice was an "Other:" choice that allowed the participant to enter their own text.

    Image choice

    Example element data

    {
      "element_id": 666941,
      "element_type": "image_choice",
      "question_text": "Please pick your two favorite images:",
      "description_text": "You need to pick exactly 2 choices.",
      "properties": {
        "choices": [
          {
            "choice_id": 6244,
            "text": "Beach",
            "image_url": "https://s3-eu-west-1.amazonaws.com/surveyhero-image-choice/666941-6244-e1d86fa737d1bdfdc97aca8b172391e6.jpg"
          },
          {
            "choice_id": 6245,
            "text": "Woods",
            "image_url": "https://s3-eu-west-1.amazonaws.com/surveyhero-image-choice/666941-6245-45848a2f16010e8bb1f0a0d2c8b8ba45.jpg"
          },
          {
            "choice_id": 6246,
            "text": "Mountains",
            "image_url": "https://s3-eu-west-1.amazonaws.com/surveyhero-image-choice/666941-6246-c3597578a5b0894bb38603fa799cda18.jpg"
          }
        ]
      },
      "validations": {
        "is_required": false,
        "allow_multiple_choices": true,
        "min_number_of_choices": 2,
        "max_number_of_choices": 2
      }
    }
    

    Example response data

    {
      "element_id": 666941,
      "element_type": "image_choice",
      "question_text": "Please pick your two favorite images:",
      "answer": {
        "type": "choices",
        "value": [
          {
            "choice_id": 6244,
            "text": "Beach",
            "image_url": "https://s3-eu-west-1.amazonaws.com/surveyhero-image-choice/666941-6244-e1d86fa737d1bdfdc97aca8b172391e6.jpg"
          },
          {
            "choice_id": 6245,
            "text": "Woods",
            "image_url": "https://s3-eu-west-1.amazonaws.com/surveyhero-image-choice/666941-6245-45848a2f16010e8bb1f0a0d2c8b8ba45.jpg"
          }
        ]
      }
    }
    

    Example of an image choice question

    Element properties

    Property Type Description
    properties.choices object[] Array with one object per available choice within multiple choice question.
    properties.choices[].choice_id integer Unique identifier of the choice.
    properties.choices[].text string Choice text visible to the participant.
    properties.choices[].image_url string|null Url path to image visible to the participant. null if no image was uploaded yet.
    validations.allow_multiple_choices boolean Whether the multiple choice question allows multiple selections or only one.
    validations.min_number_of_choices integer|null Minimum number of choices a participant must make. Will always be null if allow_multiple_choicesisfalse`.
    validations.max_number_of_choices integer|null Maximum number of choices a participant can make. Will always be null if allow_multiple_choicesisfalse`.

    Answer properties

    Property Type Description
    answer.type string Available types: choices
    answer.value object[] Array of choices, listing choices selected by participant.

    Ranking

    Example element data

    {
      "element_id": 1238491,
      "element_type": "ranking",
      "question_text": "Please rank the following in order of importance to you, first being the most important:",
      "description_text": "",
      "properties": {
        "choices": [
          {
            "choice_id": 3132165,
            "text": "Health"
          },
          {
            "choice_id": 3132166,
            "text": "Family & Friends"
          },
          {
            "choice_id": 3132167,
            "text": "Purpose"
          },
          {
            "choice_id": 3132168,
            "text": "Freedom"
          },
          {
            "choice_id": 3132169,
            "text": "Money"
          }
        ]
      },
      "validations": {
        "is_required": true,
        "allow_not_applicable": true
      }
    }
    

    Example response data

    {
      "element_id": 1238491,
      "element_type": "ranking",
      "question_text": "Please rank the following in order of importance to you, first being the most important:",
      "answer": {
        "type": "ranking",
        "value": {
          "ranked_choices": [
            {
              "choice_id": 3132165,
              "text": "Health"
            },
            {
              "choice_id": 3132166,
              "text": "Family & Friends"
            },
            {
              "choice_id": 3132167,
              "text": "Purpose"
            }
          ],
          "not_applicable_choices": [
            {
              "choice_id": 3132169,
              "text": "Money"
            }
          ]
        }
      }
    }
    

    Example of a ranking question

    Element properties

    Property Type Description
    properties.choices object[] Array with one object per available choice within ranking question.
    properties.choices[].choice_id integer Unique identifier of the choice.
    properties.choices[].text string Choice text visible to the participant.
    validations.allow_not_applicable boolean This allows a participant to mark a ranking option as "not applicable", allowing them to omit the option from the ranking.

    Answer properties

    Property Type Description
    answer.type string Available types: ranking
    answer.value object Object containing two properties: ranked_choices and not_applicable_choices
    answer.value.ranked_choices object[] Array containing the items that the participant considered in their ranking. The order of this array matches the ranking order done by the participant.
    answer.value.not_applicable_choices object[] Array containing the items that the participant did explicitly not consider in their ranking (marked as "not applicable").

    Date

    Example element data

    {
      "element_id": 666971,
      "element_type": "date",
      "question_text": "Please choose a date:",
      "description_text": "",
      "properties": {
        "text_before_input": "",
        "text_after_input": "",
        "default_value": "2018-02-01"
      },
      "validations": {
        "is_required": false
      }
    }
    

    Example response data

    {
      "element_id": 666971,
      "element_type": "date",
      "question_text": "Please choose a date:",
      "answer": {
        "type": "date",
        "value": "2018-02-15"
      }
    }
    

    Example of a date picker question

    Element properties

    Property Type Description
    properties.text_before_input string Additional text before the date picker.
    properties.text_after_input string Additional text after the date picker.
    properties.default_value string|null Default value of the date picker; can either be null if blank, a custom date in format YYYY-MM-DD (e.g. "2018-02-01") or "CURRENT_DAY" meaning it will automatically pre-fill the current date according to the participant's time zone.

    Answer properties

    Property Type Description
    answer.type string Available types: date
    answer.value string|null The date that was picked by the participant in format YYYY-MM-DD (e.g. "2018-02-15") or null if no selection was made.

    Rating

    Example element data

    {
      "element_id": 666972,
      "element_type": "rating",
      "question_text": "How would you rate our product?",
      "description_text": "",
      "properties": {
        "left_text": "Miserable",
        "right_text": "Excellent",
        "number_of_choices": 5
      },
      "validations": {
        "is_required": false
      }
    }
    

    Example response data

    {
      "element_id": 666972,
      "element_type": "rating",
      "question_text": "How would you rate our product?",
      "answer": {
        "type": "number",
        "number": 4
      }
    }
    

    Example of a rating question

    Element properties

    Property Type Description
    properties.left_text string Text that is shown above the first icon (lowest rating).
    properties.right_text string Text that is shown above the last icon (highest rating).
    properties.number_of_choices integer Number of rating choices. Can be any number between 1 and 10.

    Answer properties

    Property Type Description
    answer.type string Available types: number
    answer.value integer|null Rating given by the participant or null if no selection was made.

    Net Promoter Score

    Example element data

    {
      "element_id": 666974,
      "element_type": "net_promoter_score",
      "question_text": "How likely is it that you would recommend us to a friend or colleague?",
      "description_text": "",
      "properties": {
        "left_text": "Not at all likely",
        "right_text": "Extremely likely"
      },
      "validations": {
        "is_required": false
      }
    }
    

    Example response data

    {
      "element_id": 666974,
      "element_type": "net_promoter_score",
      "question_text": "How likely is it that you would recommend us to a friend or colleague?",
      "answer": {
        "type": "number",
        "number": 9
      }
    }
    

    Example of a Net Promoter Score (NPS) question

    Element properties

    Property Type Description
    properties.left_text string Text that is shown on the very left (lowest score).
    properties.right_text string Text that is shown on the very right (highest score).

    Answer properties

    Property Type Description
    answer.type string Available types: number
    answer.value integer|null Score given by the participant or null if no selection was made. Possible scores range from 0 to 10.

    Slider

    Example element data

    {
      "element_id": 1105155,
      "element_type": "slider",
      "question_text": "In general, what is more important to you?",
      "description_text": "",
      "properties": {
        "value_left": -100,
        "value_right": 100,
        "left_text": "Leisure",
        "right_text": "Money"
      },
      "validations": {
        "is_required": false
      }
    }
    

    Example response data

    {
      "element_id": 1105155,
      "element_type": "slider",
      "question_text": "In general, what is more important to you?",
      "answer": {
        "type": "number",
        "number": -20
      }
    }
    

    Example of a slider question (or "Visual Analogue Scale")

    Element properties

    Property Type Description
    properties.value_left integer Numerical value assigned to left end of slider (is always smaller than value_right). Can also be a negative number (signed).
    properties.value_right integer Numerical value assigned to right end of slider (is always bigger than value_left). Can also be a negative number (signed).
    properties.left_text string Text that is shown on the very left of the slider.
    properties.right_text string Text that is shown on the very right of the slider.

    Answer properties

    Property Type Description
    answer.type string Available types: number
    answer.value integer|null Position chosen on the slider, considering that the left end equals to properties.value_left and the right end equals to properties.value_right. Is null if no selection was made. Possible values range from properties.value_left to properties.value_right. Can also be a negative number (signed).

    File Upload

    Example element data

    {
      "element_id": 1387752,
      "element_type": "file_upload",
      "question_text": "Please upload your image here:",
      "description_text": "",
      "properties": {
        "max_file_size_in_mb": 25,
        "accepted_file_types": [
          "gif",
          "jpg",
          "jpeg",
          "png"
        ]
      },
      "validations": {
        "is_required": false
      }
    }
    

    Example response data

    {
      "element_id": 1387752,
      "element_type": "file_upload",
      "question_text": "Please upload your image here:",
      "answer": {
        "type": "file",
        "value": {
          "name": "Galapagos.jpg",
          "size": 480447,
          "path": "/v1/download/element/1387752/response/3875825"
        }
      }
    }
    

    Example of a rating question

    Element properties

    Property Type Description
    properties.max_file_size_in_mb integer Maximum allowed file size in megabytes per uploaded file.
    properties.accepted_file_types string[] Array of allowed file extensions (without leading dot/period) for uploaded files.

    Answer properties

    Property Type Description
    answer.type string Available types: file
    answer.value object|null If a file was uploaded, its name, size and path will be available here. If no file was uploaded, this will be null.
    answer.value.name string The file name of the uploaded file.
    answer.value.size integer The file size of the uploaded file, in bytes.
    answer.value.path string The file path to download the file body. Follow this path to download the content of the uploaded file.

    Multiple choice table

    Example element data

    {
      "element_id": 666978,
      "element_type": "multiple_choice_table",
      "question_text": "On which days do you use following products:",
      "description_text": "You can select multiple options per row.",
      "properties": {
        "rows": [
          {
            "row_id": 1745892,
            "text": "Product A"
          },
          {
            "row_id": 1745893,
            "text": "Product B"
          },
          {
            "row_id": 1745894,
            "text": "Product C"
          }
        ],
        "choices": [
          {
            "choice_id": 177294,
            "text": "Mon"
          },
          {
            "choice_id": 177295,
            "text": "Tue"
          },
          {
            "choice_id": 177296,
            "text": "Wed"
          },
          {
            "choice_id": 177297,
            "text": "Thu"
          },
          {
            "choice_id": 177298,
            "text": "Fri"
          }
        ]
      },
      "validations": {
        "is_required": false,
        "allow_multiple_choices_per_row": true
      }
    }
    

    Example response data

    {
      "element_id": 666978,
      "element_type": "multiple_choice_table",
      "question_text": "On which days do you use following products:",
      "answer": {
        "type": "choice_table",
        "value": [
          {
            "row_id": 1745892,
            "text": "Product A",
            "answer": {
              "type": "choices",
              "value": [
                {
                  "choice_id": 177295,
                  "text": "Tue"
                },
                {
                  "choice_id": 177297,
                  "text": "Thu"
                }
              ]
            }
          },
          {
            "row_id": 1745894,
            "text": "Product C",
            "answer": {
              "type": "choices",
              "value": [
                {
                  "choice_id": 177296,
                  "text": "Wed"
                }
              ]
            }
          }
        ]
      }
    }
    

    Example of a table question allowing multiple choices per row

    Element properties

    Property Type Description
    properties.rows object[] Array with one object per table row.
    properties.rows[].row_id integer Unique identifier of table row.
    properties.rows[].text string Row description that is visible to the participant.
    properties.choices object[] Array with one object per choice (column).
    properties.choices[].choice_id integer Unique identifier of choice (column).
    properties.choices[].text string Choice description that is visible to the participant.
    validations.allow_multiple_choices_per_row boolean Whether a participant can make multiple selection within a single row.

    Answer properties

    Property Type Description
    answer.type string Available types: choice_table
    answer.value object[] Array of row objects. Will only contain rows that have had at least one choice selection in it.
    answer.value[].row_id integer Unique identifier of table row.
    answer.value[].text string Row description that is visible to the participant.
    answer.value[].answer object Answer object.
    answer.value[].answer.type string Available types: choices
    answer.value[].answer.value object[] Array of choices, listing choices selected by participant in this very row.

    Numeric input table

    Example element data

    {
      "element_id": 666981,
      "element_type": "numeric_input_table",
      "question_text": "How many hours per day do you use following products:",
      "description_text": "Please only enter numbers.",
      "properties": {
        "rows": [
          {
            "row_id": 1745901,
            "text": "Product A"
          },
          {
            "row_id": 1745902,
            "text": "Product B"
          },
          {
            "row_id": 1745903,
            "text": "Product C"
          }
        ],
        "columns": [
          {
            "column_id": 177301,
            "text": "Mon"
          },
          {
            "column_id": 177302,
            "text": "Tue"
          },
          {
            "column_id": 177303,
            "text": "Wed"
          },
          {
            "column_id": 177304,
            "text": "Thu"
          },
          {
            "column_id": 177305,
            "text": "Fri"
          }
        ]
      },
      "validations": {
        "is_required": false
      }
    }
    

    Example response data

    {
      "element_id": 666981,
      "element_type": "numeric_input_table",
      "question_text": "How many hours per day do you use following products:",
      "answer": {
        "type": "input_table",
        "value": [
          {
            "row_id": 1745901,
            "text": "Product A",
            "columns": [
              {
                "column_id": 177302,
                "text": "Tue",
                "answer": {
                  "type": "number",
                  "value": 1.5
                }
              },
              {
                "column_id": 177304,
                "text": "Thu",
                "answer": {
                  "type": "number",
                  "value": 1.5
                }
              }
            ]
          },
          {
            "row_id": 1745903,
            "text": "Product C",
            "columns": [
              {
                "column_id": 177303,
                "text": "Wed",
                "answer": {
                  "type": "number",
                  "value": 3
                }
              }
            ]
          }
        ]
      }
    }
    

    Example of a table question allowing numerical inputs

    Element properties

    Property Type Description
    properties.rows object[] Array with one object per table row.
    properties.rows[].row_id integer Unique identifier of table row.
    properties.rows[].text string Row description that is visible to the participant.
    properties.columns object[] Array with one object per column.
    properties.columns[].choice_id integer Unique identifier of column.
    properties.columns[].text string Column description that is visible to the participant.

    Answer properties

    Property Type Description
    answer.type string Available types: choice_table
    answer.value object[] Array of row objects. Will only contain rows that have had at least one choice selection in it.
    answer.value[].row_id integer Unique identifier of table row.
    answer.value[].text string Row description that is visible to the participant.
    answer.value[].columns object[] Array of columns with each column that has received an answer (input) through the participant.
    answer.value[].columns[].row_id integer Unique identifier of table columns.
    answer.value[].columns[].text string Column description that is visible to the participant.
    answer.value[].columns[].answer object Answer object.
    answer.value[].columns[].answer.type string Available types: number
    answer.value[].columns[].answer.value integer|float Numeric value that was entered by the participant in that very row and column (coordinates).

    Text input table

    Example element data

    {
      "element_id": 667012,
      "element_type": "text_input_table",
      "question_text": "Please enter your contact details:",
      "description_text": "",
      "properties": {
        "rows": [
          {
            "row_id": 1745983,
            "text": "First and last name"
          },
          {
            "row_id": 1745984,
            "text": "Street address"
          },
          {
            "row_id": 1745985,
            "text": "Postal code and city"
          },
          {
            "row_id": 1745986,
            "text": "Phone number"
          },
          {
            "row_id": 1745987,
            "text": "Email address"
          }
        ],
        "columns": [
          {
            "column_id": 177308,
            "text": ""
          }
        ]
      },
      "validations": {
        "is_required": false
      }
    }
    

    Example response data

    {
      "element_id": 667012,
      "element_type": "text_input_table",
      "question_text": "Please enter your contact details:",
      "answer": {
        "type": "input_table",
        "value": [
          {
            "row_id": 1745983,
            "text": "First and last name",
            "columns": [
              {
                "column_id": 177308,
                "text": "",
                "answer": {
                  "type": "text",
                  "value": "John Smith"
                }
              }
            ]
          },
          {
            "row_id": 1745985,
            "text": "Postal code and city",
            "columns": [
              {
                "column_id": 177308,
                "text": "",
                "answer": {
                  "type": "text",
                  "value": "8008 Z├╝rich"
                }
              }
            ]
          },
          {
            "row_id": 1745987,
            "text": "Email address",
            "columns": [
              {
                "column_id": 177308,
                "text": "",
                "answer": {
                  "type": "text",
                  "value": "support@surveyhero.com"
                }
              }
            ]
          }
        ]
      }
    }
    

    Example of a form

    Element properties

    Property Type Description
    properties.rows object[] Array with one object per table row.
    properties.rows[].row_id integer Unique identifier of table row.
    properties.rows[].text string Row description that is visible to the participant.
    properties.columns object[] Array with one object per column.
    properties.columns[].choice_id integer Unique identifier of column.
    properties.columns[].text string Column description that is visible to the participant.

    Answer properties

    Property Type Description
    answer.type string Available types: choice_table
    answer.value object[] Array of row objects. Will only contain rows that have had at least one choice selection in it.
    answer.value[].row_id integer Unique identifier of table row.
    answer.value[].text string Row description that is visible to the participant.
    answer.value[].columns object[] Array of columns with each column that has received an answer (input) through the participant.
    answer.value[].columns[].row_id integer Unique identifier of table columns.
    answer.value[].columns[].text string Column description that is visible to the participant.
    answer.value[].columns[].answer object Answer object.
    answer.value[].columns[].answer.type string Available types: text
    answer.value[].columns[].answer.value string Numeric value that was entered by the participant in that very row and column (coordinates).

    Title

    Example element data

    {
      "element_id": 666755,
      "element_type": "static_title",
      "text": "Customer Satisfaction Survey"
    }
    

    Example of a header

    Element properties

    Property Type Description
    text string Content of title element.

    Text paragraph

    Example element data

    {
      "element_id": 666756,
      "element_type": "static_text",
      "text": "You had recently contacted our customer service hotline. We constantly strive to improve our service and are therefore interested in your experience. Please take a few moments to complete this satisfaction survey."
    }
    

    Example of a text paragraph

    Element properties

    Property Type Description
    text string Content of text paragraph.

    Separator

    Example element data

    {
      "element_id": 666757,
      "element_type": "static_separator"
    }
    

    Example of a separator

    Element properties

    This simple element type has no additional properties.

    Image

    Example element data

    {
      "element_id": 667014,
      "element_type": "static_image",
      "text": "Punta Espinosa, Galapagos",
      "image_url": "https://d2f1nx482ui1xj.cloudfront.net/667014-96653577dcfc6eff2a57fcfb4c2bb843.jpg"
    }
    

    Example of an image

    Element properties

    Property Type Description
    text string Text description of image, shown above the image.
    image_url string|null Url path to image visible to the participant. null if no image was uploaded yet.

    Webhooks

    Introduction to webhooks

    SurveyHero can send notifications to your application any time an event happens with one of your surveys. This is especially useful for events that are not triggered by a direct API request. For example, the most requested webhook is for "newly submitted survey responses".

    You can register webhook URLs that we will notify any time an event happens. When the event occurs - for example, a new survey response was submitted - SurveyHero will make an HTTP POST request to any endpoints that you have provided us. Each request will contain all the relevant information about what just happened, including the type of event and the data associated with that event.

    Receiving webhook notifications

    Webhook data is sent as JSON (Content-Type: application/json) in the POST request body.

    To acknowledge receipt of a webhook, your endpoint must return a 2xx HTTP status code. All response codes outside this range will indicate to SurveyHero that you did not receive or where not able to successfully process the webhook notification.

    If your endpoint does not respond with a 2xx HTTP status code, SurveyHero will attempt to deliver your webhooks again later. We will attempt to deliver your webhooks for up to three days, with hourly pauses between every retry.

    A great resource for testing is Webhook Tester. This service allows you to create temporary endpoints and to view incoming webhook notifications in real-time.

    Example webhook payload

    Example webhook notification payload

    {
      "message_id": "356042f5-44d7-416f-8c71-b5b254b9baa5",
      "triggered_on": "2018-12-09T16:06:18+0000",
      "webhook": {
        "webhook_id": 1,
        "event_type": "response.completed",
        "url": "https://webhook.site/a4ed275d-9954-4fe1-91ea-2ec4da5016e8",
        "status": "active",
        "created_on": "2018-12-09T16:02:25+0000"
      },
      "data": {
        // Data specific to event type, e.g. complete survey response
      }
    }
    

    Each webhook notification will contain this information. The content of the data property will change based on the event type.

    Property Type Description
    message_id string Unique message identifier. Every webhook notification will have a unique message ID. If a delivery fails and we have to retry again, the ID will remain the same.
    triggered_on timestamp Timestamp of when the event was triggered.
    webhook object The corresponding webhook that is responsible for this request.
    data object The data corresponding to the event type. In case of event type response.completed, this will be the complete survey response.

    Webhooks Endpoints

    Here is an overview of the available actions to manage your webhooks:

    HTTP request Description
    GET https://api.surveyhero.com/v1/surveys/{survey_id}/webhooks List all webhooks of survey.
    POST https://api.surveyhero.com/v1/surveys/{survey_id}/webhooks Create a new webhook for survey.
    GET https://api.surveyhero.com/v1/surveys/{survey_id}/webhooks/{webhook_id} Get details of specific webhook.
    POST https://api.surveyhero.com/v1/surveys/{survey_id}/webhooks/{webhook_id} Update specific webhook.
    DELETE https://api.surveyhero.com/v1/surveys/{survey_id}/webhooks/{webhook_id} Delete specific webhook.

    List existing webhooks

    Example request

    curl -X GET "https://api.surveyhero.com/v1/surveys/1000/webhooks" \
         -u "username:password"
    

    Example response

    {
        "webhooks": [
            {
                "webhook_id": 1000,
                "event_type": "response.completed",
                "url": "https://webhook.site/a4ed275d-9954-4fe1-91ea-2ec4da5016e8",
                "status": "active",
                "created_on": "2018-12-09T16:02:25+0000"
            },
            {
                "webhook_id": 1001,
                "event_type": "response.completed",
                "url": "https://integration.acme-company.com/process-new-response",
                "status": "paused",
                "created_on": "2018-12-09T16:41:37+0000"
            }
        ]
    }
    

    You can view all defined webhooks of a specific survey. You can then use the webhook_id to make an update to or delete a webhook.

    HTTP request

    GET https://api.surveyhero.com/v1/surveys/{survey_id}/webhooks

    Response properties

    Property Type Description
    webhook object[] Array with one object per available webhook.

    Create a new webhook

    Example request

    curl -X POST "https://api.surveyhero.com/v1/surveys/1000/webhooks" \
         -u "username:password" \
         -F "event_type=response.completed" \
         -F "url=https://integration.acme-company.com/process-new-response"
    

    Example response

    {
      "webhook_id": 1001,
      "event_type": "response.completed",
      "url": "https://integration.acme-company.com/process-new-response",
      "status": "active",
      "created_on": "2018-12-09T16:41:37+0000"
    }
    

    You can simply create a new webhook for a survey by navigating to the specific survey's resource and making an HTTP POST request with the required parameters.

    HTTP request

    POST https://api.surveyhero.com/v1/surveys/{survey_id}/webhooks

    Request parameters

    Parameter Type Description
    event_type string, required The type of event you want to be notified about. Currently, response.completed is the only available event type. Want to be notified about other events, too? Contact us!
    url string, required The URL where you want us to send the notifications. This should be an active endpoint, pointing to your application or server. You may want to use Webhook Tester for testing.
    status string Whether the webhook should be active (default) or paused.

    Response properties

    The request will either return the newly created webhook details on success, or an error message if creation failed (e.g. because of missing or invalid url parameter).

    Retrieve a single webhook

    Example request

    curl -X GET "https://api.surveyhero.com/v1/surveys/1000/webhooks/1001" \
         -u "username:password"
    

    Example response

    {
      "webhook_id": 1001,
      "event_type": "response.completed",
      "url": "https://integration.acme-company.com/process-new-response",
      "status": "active",
      "created_on": "2018-12-09T16:41:37+0000"
    }
    

    Retrieve the details of a specific webhook.

    HTTP request

    GET https://api.surveyhero.com/v1/surveys/{survey_id}/webhooks/{webhook_id}

    Response properties

    Property Type Description
    webhook_id integer Unique identifier for the webhook.
    event_type string What event the webhook is notifying about. Currently, response.completed is the only event type available. Need more? Let us know!
    url string The endpoint where we will send notifications to.
    status string Whether the webhook is active (default) or paused.
    created_on timestamp Timestamp of when the webhook was created.

    Update an existing webhook

    Example request

    curl -X POST "https://api.surveyhero.com/v1/surveys/1000/webhooks/1001" \
         -u "username:password" \
         -F "status=paused"
    

    Example response

    {
      "webhook_id": 1001,
      "event_type": "response.completed",
      "url": "https://integration.acme-company.com/process-new-response",
      "status": "paused",
      "created_on": "2018-12-09T16:41:37+0000"
    }
    

    You can always update an existing webhook. You can either change the url or change the webhook status.

    HTTP request

    POST https://api.surveyhero.com/v1/surveys/{survey_id}/webhooks/{webhook_id}

    Request parameters

    Parameter Type Description
    url string The URL where you want us to send the notifications. This should be an active endpoint, pointing to your application or server.
    status string Whether the webhook should be active (default) or paused.

    Response properties

    The request will either return the updated webhook details on success, or an error message if the update failed (e.g. because of invalid url parameter).

    Delete a webhook

    Example request

    curl -X DELETE "https://api.surveyhero.com/v1/surveys/1000/webhooks/1001" \
         -u "username:password"
    

    Example response

    {
      "webhook_id": 1001,
      "event_type": "response.completed",
      "url": "https://integration.acme-company.com/process-new-response",
      "status": "deleted",
      "created_on": "2018-12-09T16:41:37+0000"
    }
    

    You can simply delete webhooks when you do not need them anymore. Alternatively, you can also change its status to paused.

    HTTP request

    DELETE https://api.surveyhero.com/v1/surveys/{survey_id}/webhooks/{webhook_id}

    Response properties

    The request will either return the webhook that was deleted, or an error message if deletion failed (e.g. because webhook was already deleted before).

    Errors

    Example error response

    {
      "error": {
        "code": 40140,
        "message": "Authentication failed: API key is deactivated"
      }
    }
    

    When consuming our API you may face errors. We try to make them as descriptive as possible, so you can resolve them as easily as possible. In general, codes in the 2xx range indicate success, codes in the 4xx range are errors caused in your request while codes in the 5xx range are errors on our end. Here is an overview of different errors and their meaning.

    HTTP Status Error Code Meaning
    400 40000 Bad Request
    400 40010 Missing required parameter, unable to complete request
    400 40020 Invalid parameter value, unable to complete request
    400 40030 Duplicate value: Request could not be completed because value already exists
    401 40100 Unauthorized
    401 40110 Authentication failed: Missing or incomplete authorization header
    401 40120 Authentication failed: Invalid format of credentials in authorization header
    401 40130 Authentication failed: Unknown credentials in authorization header
    401 40140 Authentication failed: API key is deactivated
    403 40300 Forbidden
    403 40310 Forbidden: You are not allowed access to this survey
    404 40400 Resource Not Found
    404 40450 Resource Not Found: Response ID does not belong to survey ID
    405 40500 Method Not Allowed
    429 42910 Too Many Requests: Please do not make more than 2 requests per second
    500 50000 Internal Server Error
    503 50300 Service Unavailable

    Feedback and Support

    Thank you for your interest in our API.

    We will be continuously adding new and exciting capabilities to it. Feedback is very welcome and if you need to be able to do something programmatically that is not possible yet, please let us know!