Olery Developer Portal logo Olery Developer Portal

Feedback Surveys

[PUT] Create Survey

Method Path
PUT https://agora.olery.com/v3/feedback/surveys

This endpoint is used to create a survey. It returns the created survey.

Input Parameters

The request’s body can have the following fields:

Field Required Data Types Description
name true String Survey’s Name
published false Boolean Survey’s status (active or inactive)
languages true Array Array of strings where each element is a language code
default_locale true String Survey’s default language code
translations false Hash See Translations Field section
redirect_url false String Survey’s redirection URL
question_ids false Array Array of strings. Each string denotes a question ID linked to the survey, it can be used to add existing questions
conditions false Array See Conditions section
company_ids true Array Array of Olery IDs of companies you want to use in this survey
logo false MultiFormat Logo image upload (can be done in a separate api call)
bg false MultiFormat Background image upload (can be done in a separate api call)
color_hex false String Hexadecimal code for the survey’s color

Translations Field

The translation field is a hash where each key is a languages code. Each key has a hash with the following fields:

Field Data Types Description
title String Survey’s title in that language
thankyou String Survey’s thank you message in that language
instructions String Survey’s instructions in that language
redirect_message false Survey’s redirection message in that language

Conditions

The conditions field is an array of hashes where every hash represents a logical condition. Every hash has the following fields:

Field Data Types Description
level String Condition level, it can be question or group
published Boolean Indicates if the logical condition is enabled or not
source Hash Hash with the action, source question’s ID, type of relation between the question’s answers and the value
target String The target question’s ID

The action field inside source is can be one of the following: show, hide or jump, denoted by a string. The value can be a string or a number that denotes a value to be watched in the source question’s answer to perform the action between the source and target questions. The type can be one of the following, according to the type of the source question:

Question Type Compatible Types
date less_than, less_or_equal_to, is_equal_to, is_not_equal_to, more_or_equal_to, more_than
drop_down contains, doesnt_contain
enum is_equal_to, is_not_equal_to
multiple_select contains, doesnt_contain
open_answer contains, doesnt_contain, begins_with, ends_with
open_answer_long contains, doesnt_contain, begins_with, ends_with
past_date less_than, less_or_equal_to, is_equal_to, is_not_equal_to, more_or_equal_to, more_than
rating less_than, less_or_equal_to, is_equal_to, is_not_equal_to, more_or_equal_t, more_than
yes_no is_equal_to, is_not_equal_to

Example Input 

{
  "name": "Demo Survey",
  "title": "Give us feedback",
  "published": true,
  "instructions": null,
  "languages": ["en", "es"],
  "default_locale": "en",
  "translations": {
    "en": {
      "title": "Give us feedbacks",
      "thankyou": "Thank you for giving us your opinion!",
      "instructions": "We are very interested to hear what you think. We would appreciate if you could spare a few moments to complete this survey."
    },
    "es": {
      "title": "Danos su opinión",
      "thankyou": "¡Gracias por darnos tu opinión!",
      "instructions": "Estamos muy interesados ​​en escuchar lo que piensas. Le agradeceríamos que nos dedicara unos minutos a completar esta encuesta."
    }
  },
  "redirect_message": "Thank you for answering the survey. You will be redirected to a Google Form.",
  "redirect_url": "https://docs.google.com/forms",
  "question_ids": ["959d32ab8cbfi4b70bff1324e"],
  "conditions": [
    {
      "level": "question",
      "published": true,
      "source": {
        "action": "show",
        "id": "959d32ab8cbfi4b70bffjdnbv7",
        "type": "contains",
        "value": "certain value"
      },
      "target": { "id": "493nmv7lb8cbfi4b70bff1324e" }
    }
  ],
  "company_ids": ["8347788"],
  "logo_url": "https://dzm1xrrk9dqdf.cloudfront.net/uploads/company/logo/8347788/37805b128f.png",
    "bg_url": "https://dzm1xrrk9dqdf.cloudfront.net/uploads/company/background/582681/cd274696b7a8cf72be60.jpg",
    "color_hex": "#55C5CC"
}

Output Format

The return is the survey created, which has the same fields as stated above, but with some extra ones:

Field Data Types Description
questions Hash Array of hashes, each hash follows this structure
items Array See Survey Items Fields section

Survey Items Fields

This field is an array of hashes. Each hash contains the following fields:

Field Data Types Description
type String Item’s type
object Hash or Array Language code

The item represents a question or a group of questions. If it is a question, the type will be question and the object field will be a hash representing the question with the same fields as in this section. If the item represents a group of questions, the type will be group and the object field will be an array of questions.

Example Output

The output to the input we described is stated below.

{
  "data": {
    "id": "acca563caf73763bc9a018fc9",
    "name": "Demo Survey",
    "title": "Give us feedback",
    "published": true,
    "instructions": null,
    "languages": ["en", "es"],
    "default_locale": "en",
    "translations": {
      "en": {
        "title": "Give us feedbacks",
        "thankyou": "Thank you for giving us your opinion!",
        "instructions": "We are very interested to hear what you think. We would appreciate if you could spare a few moments to complete this survey."
      },
      "es": {
        "title": "Danos su opinión",
        "thankyou": "¡Gracias por darnos tu opinión!",
        "instructions": "Estamos muy interesados ​​en escuchar lo que piensas. Le agradeceríamos que nos dedicara unos minutos a completar esta encuesta."
      }
    },
    "redirect_message": "Thank you for answering the survey. You will be redirected to a Google Form.",
    "redirect_url": "https://docs.google.com/forms",
    "questions": [
      {
        "id": "959d32ab8cbfi4b70bff1324e",
        "question": "Example question",
        "type": "multiple_select",
        "descriptions": [
          {
            "_id": "en",
            "locale": "en",
            "translation": "Example description"
          },
          {
            "_id": "es",
            "locale": "es",
            "translation": "Ejemplo de descripción"
          }
        ],
        "translations": [
          {
            "_id": "en",
            "locale": "en",
            "translation": "Example question"
          },
          {
            "_id": "es",
            "locale": "es",
            "translation": "Ejemplo de pregunta"
          }
        ],
        "max": null,
        "min": null,
        "max_value": null,
        "required": true,
        "enabled_followup": false,
        "links": [
          {
            "en": {
              "url": "https://example.com/terms",
              "title": "Terms and Conditions"
            }
          }
        ],
        "options": [
          {
            "en": "English option 1",
            "es": "Opción española 1",
            "id": "english option 1",
            "default": "English option 1"
          },
          {
            "en": "English option 2",
            "es": "Opción española 2",
            "id": "english option 2",
            "default": "English option 2"
          }
        ],
        "config": {},
        "topics": ["bar", "sanitary_safety"]
      }
    ],
    "settings": null,
    "conditions": [
      {
        "level": "question",
        "source": {
          "id": "959d32ab8cbfi4b70bffjdnbv7",
          "type": "contains",
          "value": "certain value",
          "action": "show"
        },
        "target": {
          "id": "493nmv7lb8cbfi4b70bff1324e"
        },
        "published": true
      }
    ],
    "company_ids": ["8347788"],
    "items": [
      {
        "type": "question",
        "object": {
          "id": "959d32ab8cbfi4b70bff1324e",
          "question": "Example question",
          "type": "multiple_select",
          "descriptions": [
            {
              "_id": "en",
              "locale": "en",
              "translation": "Example description"
            },
            {
              "_id": "es",
              "locale": "es",
              "translation": "Ejemplo de descripción"
            }
          ],
          "translations": [
            {
              "_id": "en",
              "locale": "en",
              "translation": "Example question"
            },
            {
              "_id": "es",
              "locale": "es",
              "translation": "Ejemplo de pregunta"
            }
          ],
          "max": null,
          "min": null,
          "max_value": null,
          "required": true,
          "enabled_followup": false,
          "links": [
            {
              "en": {
                "url": "https://example.com/terms",
                "title": "Terms and Conditions"
              }
            }
          ],
          "options": [
            {
              "en": "English option 1",
              "es": "Opción española 1",
              "id": "english option 1",
              "default": "English option 1"
            },
            {
              "en": "English option 2",
              "es": "Opción española 2",
              "id": "english option 2",
              "default": "English option 2"
            }
          ],
          "config": {},
          "topics": ["bar", "sanitary_safety"]
        }
      }
    ],
    "question_ids": ["959d32ab8cbfi4b70bff1324e"],
    "logo_url": "https://dzm1xrrk9dqdf.cloudfront.net/uploads/company/logo/8347788/37805b128f.png",
    "bg_url": "https://dzm1xrrk9dqdf.cloudfront.net/uploads/company/background/582681/cd274696b7a8cf72be60.jpg",
    "color_hex": "#55C5CC"
  }
}