Suggested improvements to the payload definition

Hello,

Right now our typeform survey makes good use of the webhooks to send each response payload through our ETL backend for processing and analysis.

It’s been about six weeks and while we have things working, I have suggestions for improvements i’d like to see that would enable things to work better for us.

For us, typeform is a great way for the non-technical members of our team to have the ability to build a survey that looks good and quickly make changes from customer feedback.

However, as it stands we can run into issues where changes to the survey made from the admin create panel can easily break our ETL pipeline. We’d like to solve some of these problems and I have some suggestions that I think would help that I hope would not require a large amount of effort to implement.

Improvements to the payload

I want to discuss the relationship between the field objects and correspondent answer objects in the payload.

extract of the payload structure:

{
   "form_response": {
      "definition": {
         "fields": [
         ]
      },
      "answers": [
      ]
   }
}

Problem: multiple selection

Some questions, such as picture_choice, multiple_choice,  dropdown can have multiple answers selected.

In the admin create panel, a range can be placed on the number of answers selected. However currently there is no way of knowing from the payload definition what this range is.

This is problematic for our backend payload validation since we right now we need to manually check the questions to get this information

Example:

{
   "form_response": {
      "definition": {
         "fields": [
            {
              "id": "Z0W1B9ZJq45R",
              "title": "What animals do you like?",
              "type": "picture_choice",
              "allow_multiple_selections": true,
              "ref": "animals_like",
              "properties": {},
              "choices": [
                {
                  "id": "nqHeZVBfCt2L",
                  "label": "Dog"
                },
                {
                  "id": "nqHeZVBfCt2L",
                  "label": "Cat"
                }
              ]
            } 
         ]
      },
      "answers": [
          {
            "type": "choices",
            "choices": {
              "labels": ["Dog"]
            },
            "field": {
              "id": "Z0W1B9ZJq45R",
              "type": "picture_choice",
              "ref": "animals_like"
            }
          },
      ]
   }
}

Solution: multiple selection

Add a range object to the properties:

"range": { 
   "minimum"
   "maximum"
}

 Example:

{
   "form_response": {
      "definition": {
         "fields": [
            {
              "id": "Z0W1B9ZJq45R",
              "title": "What animals do you like?",
              "type": "picture_choice",
              "allow_multiple_selections": true,
              "ref": "animals_like",
              "properties": {
                 "range": { 
                     "minimum": 1,
                     "maximum": 2
                  }
              },
              "choices": [
                {
                  "id": "nqHeZVBfCt2L",
                  "label": "Dog"
                },
                {
                  "id": "nqHeZVBfCt2L",
                  "label": "Cat"
                }
              ]
            } 
         ]
      }
}

Having a range object for multiple selections AND opinion scales, other numerical questions would be very useful in allowing us to validate the payload from just the definition.

Additionally, I notice that the “allow_multiple_selections”  field is either always true, or not present. It would be preferable if this field were always present and the value not always true

Problem: dropdown questions have no “choices” object

The same picture choice question above can be easily translated to a dropdown question with the labels being preserved. However for some reason there is no “choices” object as part of the definition when a question is dropdown? This seems like it shouldn’t be the case.

Having the “choices” object in the definition is very useful for us to validate if any changes have been made to the survey between payloads. By not having this in the definition of a dropdown question it can make our pipeline open to error since we might have a bug that is only caught when a bad answer is received. Or otherwise, someone has to manually check each answer label for each dropdown question in the admin panel which is in itself error prone.

Example:

{
   "form_response": {
      "definition": {
         "fields": [
            {
              "id": "Z0W1B9ZJq45R",
              "title": "What animals do you like?",
              "type": "dropdown",
              "allow_multiple_selections": true,
              "ref": "animals_like",
              "properties": {}
         ]
      },
      "answers": [
          {
            "type": "choices",
            "choices": {
              "labels": ["Dog"]
            },
            "field": {
              "id": "Z0W1B9ZJq45R",
              "type": "dropdown",
              "ref": "animals_like"
            }
          },
      ]
   }
}

Solution: dropdown questions have no “choices” object

Should be instead:

{
   "form_response": {
      "definition": {
         "fields": [
            {
              "id": "Z0W1B9ZJq45R",
              "title": "What animals do you like?",
              "type": "dropdown",
              "allow_multiple_selections": true,
              "ref": "animals_like",
              "properties": {},
              "choices": [
                {
                  "id": "nqHeZVBfCt2L",
                  "label": "Dog"
                },
                {
                  "id": "nqHeZVBfCt2L",
                  "label": "Cat"
                }
              ]
            } 
         ]
      },
      "answers": [
          {
            "type": "choices",
            "choices": {
              "labels": ["Dog"]
            },
            "field": {
              "id": "Z0W1B9ZJq45R",
              "type": "dropdown",
              "ref": "animals_like"
            }
          },
      ]
   }
}

Problem: We don’t know which questions are required

In the admin create panel there is a switch to make a question “required”. We would like to have a field added to the definition that reflects this information so we know whether to always or only sometimes expect an answer for a given question. This would allow us to validate whether we are getting answers when we expect too.

Solution: We don’t know which questions are required

Add a boolean field to the definition

{
   "form_response": {
      "definition": {
         "fields": [
            {
              "id": "Z0W1B9ZJq45R",
              "title": "What animals do you like?",
              "type": "dropdown",
              "allow_multiple_selections": true,
              "required": true,
              "ref": "animals_like",
              "properties": {}
            }
         ]
      }
   }
}

Generating a better test request

Our survey is currently hooked to an endpoint so each payload can be processed.

Right now there are only two ways to test any changes to our survey and each has drawbacks.

1. Manually go through our survey and generate a test payload
2. In the admin/connect/webhooks panel click the test request button

I really like the idea of option 2, I’d like it if I could click the test request button and if it comes back with a response of 200 then I should be able to conclude there are no breaking changes that have been made by our marketing team. It’s a great smoke test with minimal effort.

However the problem I have is that the test request that’s generated is not good.

Right now, every answer is “Barcelona”

{
   "form_response": {
      "definition": {
         "fields": [
            {
              "id": "Z0W1B9ZJq45R",
              "title": "What animals do you like?",
              "type": "picture_choice",
              "allow_multiple_selections": true,
              "ref": "animals_like",
              "properties": {},
              "choices": [
                {
                  "id": "nqHeZVBfCt2L",
                  "label": "Dog"
                },
                {
                  "id": "nqHeZVBfCt2L",
                  "label": "Cat"
                }
              ]
            } 
         ]
      },
      "answers": [
          {
            "type": "choices",
            "choices": {
              "labels": ["Barcelona"]
            },
            "field": {
              "id": "Z0W1B9ZJq45R",
              "type": "picture_choice",
              "ref": "animals_like"
            }
          },
      ]
   }
}

Because we have validation checks, this doesn’t allow us to use this option.

I would like it if this could be improved so that a valid response could be generated. I believe if the definition object of the payload were improved by my suggestions above, it would be all the sufficient information required to generate a valid set of answers and this would provide immense value to us as a team.

API call to generate a test request

Further still to generating a test request through either the admin panel or connect panel, I would like it if I could send a GET request to return a test payload.

This would be very useful since we could then build an automated process to monitor for changes and be proactive to problems.

Thanks for reading, I hope we can discuss my problems and suggestions and collaborate on solutions.

Best regards,

Oliver