Navbar
shell
  • Introduction
  • Authentication
  • Good To Know
  • API Endpoints
  • All Element Types
  • 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+0100"
    }
    

    All timestamps are formatted according to ISO 8601. This format contains the time zone offset. The offset will be set according to your preferences in "My Account". This will allow you to comfortably read the timestamp in your own time zone, while still having the possibility to convert it to UTC if needed.

    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+0100",
          "number_of_questions": 12,
          "number_of_responses": 78
        },
        {
          "survey_id": 53635,
          "title": "Event Feedback",
          "created_on": "2018-02-27T20:12:33+0100",
          "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+0100",
      "number_of_elements": 6,
      "number_of_questions": 3,
      "number_of_responses": 2,
      "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.
    settings.is_anonymous boolean Whether it is an anonymous survey. Note: It is currently not possible to fetch responses of anonymous surveys via the API. If you need to, please contact us.
    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": {
            "text_left": "Not at all likely",
            "text_right": "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": {
            "text_left": "Not at all likely",
            "text_right": "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+0100",
          "last_modified_on": "2018-02-27T20:16:06+0100",
          "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+0100",
          "last_modified_on": "2018-02-27T20:14:27+0100",
          "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_modified_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_modified_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.
    link_parameters object Any GET parameters that were added to the survey link of the participant will show here.
    ip_address string|null If the collector was set to save IP addresses, they will show here.
    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_modified_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+0100",
      "last_modified_on": "2018-02-28T11:15:13+0100",
      "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": 664697,
          "element_type": "net_promoter_score",
          "question_text": "How likely is it that you would recommend the event to a friend or colleague?",
          "answer": {
            "number": 9
          }
        },
        {
          "element_id": 664706,
          "element_type": "multi_line_text_input",
          "question_text": "Is there anything you would like to share about the event?",
          "answer": {
            "text": "No, it was very well organized."
          }
        }
      ]
    }
    

    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. The format will be different for each 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

    {
      "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 answer

    {
      "element_id": 666811,
      "element_type": "single_line_text_input",
      "question_text": "What is your full name?",
      "answer": {
        "text": "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.text string Text answer of participant.

    Multi-line text input

    Example element

    {
      "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 answer

    {
      "element_id": 666812,
      "element_type": "multi_line_text_input",
      "question_text": "Do you have any further comments?",
      "answer": {
        "text": "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.text string Text answer of participant.

    Example element

    {
      "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 answer

    {
      "element_id": 666809,
      "element_type": "drop_down",
      "question_text": "In which department do you work?",
      "answer": {
        "choices": [
          {
            "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.choices object[] Array containing the choices that the participant selected as their answer.

    Multiple choice

    Example element

    {
      "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"
          }
        ],
        "other_choice": {
          "text": "Other"
        }
      },
      "validations": {
        "is_required": false,
        "allow_multiple_choices": true,
        "min_number_of_choices": null,
        "max_number_of_choices": null
      }
    }
    

    Example answer

    {
      "element_id": 666967,
      "element_type": "multiple_choice",
      "question_text": "Which of these courses have you already attended?",
      "answer": {
        "choices": [
          {
            "choice_id": 1745870,
            "text": "Course A"
          },
          {
            "choice_id": 1745872,
            "text": "Course C"
          }
        ],
        "other_choice": "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.
    properties.other_choice (optional) object Multiple choice questions may allow a custom entry by the participant. If this property exists, then an "other" choice text entry is available to the participant.
    properties.other_choice.text string Text before the text input of the "other" choice.
    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.choices object[] Array containing the choices that the participant selected as their answer.
    answer.other_choice string|null "Other" choice text answer from participant. null if "other" choice was not selected.

    Image choice

    Example element

    {
      "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 answer

    {
      "element_id": 666941,
      "element_type": "image_choice",
      "question_text": "Please pick your two favorite images:",
      "answer": {
        "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"
          }
        ]
      }
    }
    

    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.choices object[] Array containing the choices that the participant selected as their answer.

    Ranking

    Example element

    {
      "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 answer

    {
      "element_id": 1238491,
      "element_type": "ranking",
      "question_text": "Please rank the following in order of importance to you, first being the most important:",
      "answer": {
        "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.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.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

    {
      "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 answer

    {
      "element_id": 666971,
      "element_type": "date",
      "question_text": "Please choose a date:",
      "answer": {
        "date": "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.date 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

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

    Example answer

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

    Example of a rating question

    Element properties

    Property Type Description
    properties.text_left string Text that is shown above the first icon (lowest rating).
    properties.text_right 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.number integer|null Rating given by the participant or null if no selection was made.

    Net Promoter Score

    Example element

    {
      "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": {
        "text_left": "Not at all likely",
        "text_right": "Extremely likely"
      },
      "validations": {
        "is_required": false
      }
    }
    

    Example answer

    {
      "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": {
        "number": 9
      }
    }
    

    Example of a Net Promoter Score (NPS) question

    Element properties

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

    Answer properties

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

    Slider

    Example element

    {
      "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,
        "text_left": "Leisure",
        "text_right": "Money"
      },
      "validations": {
        "is_required": false
      }
    }
    

    Example answer

    {
      "element_id": 1105155,
      "element_type": "slider",
      "question_text": "In general, what is more important to you?",
      "answer": {
        "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.text_left string Text that is shown on the very left of the slider.
    properties.text_right string Text that is shown on the very right of the slider.

    Answer properties

    Property Type Description
    answer.number 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

    {
      "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 answer

    {
      "element_id": 1387752,
      "element_type": "file_upload",
      "question_text": "Please upload your image here:",
      "answer": {
        "file": {
          "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.file 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.file.name string The file name of the uploaded file.
    answer.file.size integer The file size of the uploaded file, in bytes.
    answer.file.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

    {
      "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 answer

    {
      "element_id": 666978,
      "element_type": "multiple_choice_table",
      "question_text": "On which days do you use following products:",
      "answer": {
        "choices": [
          {
            "row": {
              "row_id": 1745892,
              "text": "Product A"
            },
            "choice": {
              "choice_id": 177295,
              "text": "Tue"
            }
          }, 
          {
            "row": {
              "row_id": 1745892,
              "text": "Product A"
            },
            "choice": {
              "choice_id": 177297,
              "text": "Thu"
            }
          },
          {
            "row": {
              "row_id": 1745894,
              "text": "Product C"
            },
            "choice": {
              "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.choices object[] Array with one object per selection that was made within the table. The combination of row and choice (column) will give you the "coordinates" of the selections.
    answer.choices[].row object Table row that was selected.
    answer.choices[].choice object Choice (column) that was selected.

    Numeric input table

    Example element

    {
      "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 answer

    {
      "element_id": 666981,
      "element_type": "numeric_input_table",
      "question_text": "How many hours per day do you use following products:",
      "answer": {
        "entries": [
          {
            "row": {
              "row_id": 1745901,
              "text": "Product A"
            },
            "column": {
              "column_id": 177302,
              "text": "Tue"
            },
            "number": 1.5
          },
          {
            "row": {
              "row_id": 1745901,
              "text": "Product A"
            },
            "column": {
              "column_id": 177304,
              "text": "Thu"
            },
            "number": 1.5
          },
          {
            "row": {
              "row_id": 1745903,
              "text": "Product C"
            },
            "column": {
              "column_id": 177303,
              "text": "Wed"
            },
            "number": 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.entries object[] Array with one object per entry that was made within the table. The combination of row and column will give you the "coordinates" of where the entry was made.
    answer.entries.row object Table row where the entry was made.
    answer.entries.column object Table column where entry was made.
    answer.entries.number integer|float Numeric value that was entered by the participant.

    Text input table

    Example element

    {
      "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 answer

    {
      "element_id": 667012,
      "element_type": "text_input_table",
      "question_text": "Please enter your contact details:",
      "answer": {
        "entries": [
          {
            "row": {
              "row_id": 1745983,
              "text": "First and last name"
            },
            "column": {
              "column_id": 177308,
              "text": ""
            },
            "text": "John Smith"
          },
          {
            "row": {
              "row_id": 1745985,
              "text": "Postal code and city"
            },
            "column": {
              "column_id": 177308,
              "text": ""
            },
            "text": "8008 Z├╝rich"
          },
          {
            "row": {
              "row_id": 1745987,
              "text": "Email address"
            },
            "column": {
              "column_id": 177308,
              "text": ""
            },
            "text": "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.entries object[] Array with one object per entry that was made within the table. The combination of row and column will give you the "coordinates" of where the entry was made.
    answer.entries.row object Table row where the entry was made.
    answer.entries.column object Table column where entry was made.
    answer.entries[].text string Text answer that was entered by the participant.

    Title

    Example element

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

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

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

    Example of a separator

    Element properties

    This simple element type has no additional properties.

    Image

    Example element

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

    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
    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 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
    429 42910 Too Many Requests: Please do not make more than 2 requests per second
    500 50000 Oops, something went wrong! This has been logged and will be addressed as soon as possible.
    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!