Olery Developer Portal logo Olery Developer Portal

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

This endpoint is used to update an existing survey through the survey ID. It returns the updated survey.

Input Format

The request’s body can have the following fields:

Field Data Types Description
name String Survey’s Name
title String Survey’s Title
published Boolean Survey’s status (active or inactive)
instructions String Survey’s Instructions
languages Array Array of strings where each element is a language code
default_locale String Survey’s default language code
translations Hash See Translation Fields section
redirect_message String Survey’s redirection message
redirect_url String Survey’s redirection URL
question_ids Array Array of strings. Each string denotes a question ID linked to the survey, it can be used to add existing questions
conditions Array See Conditions section
company_ids Array Array of integers where each element indicates a company linked to the survey
logo_url String URL to the survey’s or company’s logo
bg_url String URL to the survey’s background
color_hex String Hexadecimal code for the survey’s color

Translation Fields

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

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 Updated",
  "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.

Questions Fields

The questions field is an array of hashes with all survey’s questions. Every hash has the following fields:

Field Data Types Description
id String Question’s ID
question String Question itself, in the default language
type String Question’s type
descriptions Array See Descriptions Fields section
translations Array Used to store question’s translations. Same structure as descriptions field
max Integer Denotes the maximum characters allowed for an answer. Used when the question type is an open answer (normal or long)
min Integer Denotes the minimum characters allowed for an answer. Used when the question type is an open answer (normal or long)
max_value Integer Denotes the maximum rating. Used when the question type is a rating
required Boolean Indicates if the question is required
enabled_followup Boolean Indicates if the question has a follow up. Only for rating questions
links Array See Links Fields section
options Array See Question Options section
config Hash See Config Fields section
topics Array Array of strings where each string represents a rating for the question

Each question can be one of the following types: date, drop_down, enum, multiple_select, open_answer, open_answer_long, past_date, rating or yes_no.

Question Descriptions Fields

The descriptions field is an array of hashes with translations for the question’s description field. The hashes have the following fields:

Field Data Types Description
locale String Language code
_id String Language code
translation String Description in that language

The links field is and array of hashes. Every hash has a language code key and it value is another hash with the following fields:

Field Data Types Description
title String The link’s text to be displayed
url String The link itself

Question Options Fields

The option field inside the question is an array of hashes used to store the option ID and its translations. This field is used when the question has one of the following types: multiple_select, enum or drop_down. Each hash in the array has the following fields:

Field Data Types Description
id String Option’s ID.
default String Option in the default language
language code String Option in the specific language.

Question Config Field

This field is used to configure rating labels for questions of the the rating. It is a hash with another hash inside with a key named edge_labels with the following fields:

Field Data Types Description
best Hash It contains bey-value pairs, where the key is a language code and the value is the label in that language
worst Hash It contains bey-value pairs, where the key is a language code and the value is the label in that language

Each of this fields has also a default key-value pair, which represents the label in the default language. It follows an example for the config field:

"config": {
  "edge_labels": {
      "best": {
          "en": "Best",
          "es": "Mejor",
          "default": "Best"
      },
      "worst": {
          "en": "Worst",
          "es": "Peor",
          "default": "Worst"
      }
  }
}

Example Output

The output to the input we described is stated below.

{
  "data": {
    "id": "acca563caf73763bc9a018fc9",
    "name": "Demo Survey Updated",
    "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"
  }
}