Forms Endpoints

Get access to forms data.

This is a step-by-step guide that shows how to use the forms endpoints.

What can you do with the forms endpoints?

The forms endpoints in the Zenput API enable you to get the following data:

  • Get Form Templates: Details about all existing form templates corresponding to your company
  • Get Form Submissions: Details about a form template and any corresponding form submissions given an existing form template ID
  • Get Form Submission: Details about a form submission given an existing form submission ID

What do you need to know about forms?

The following table contains concepts about forms.

ConceptDefinition
ActivitiesActivities are face-to-face chores that end users can complete.
FormsForms are the documents that end users utilize to track specific activities.
TemplatesTemplates represent blank forms.
End users set up forms in a web browser via the Zenput Form Builder.
SubmissionsSubmissions represent filled-out forms.
End users fill out forms on a mobile device, and then they submit them via the Zenput Mobile App.
FieldsFields correspond to the questions that end users can select and configure in a form.
Templates contain sets of blank fields.
Submissions contain sets of filled-out fields.

What resources are available via the forms endpoints?

Forms

Forms consist of the following three different top-level pieces of information:

  • fields: data about the form template's fields, which can be set up via the Zenput Form Builder
  • metadata: data about the form template
  • smetadata: data about the form submission
{
  "fields": [],
  "metadata": {},
  "smetadata": {}
}

Form Fields

Each field of any form has a plethora of information stored about it, both in its template state as well as its submission state. Below is an example of a 'Range' field

{
  "instructions":"",    // optional instructions shown to a user
  "value":"",       // this value is filled in once submitted
  "metadata":null,
  "title_image":[],
  "type":"range",       // the type of question is it, i.e. number, text, etc
  "key":"",
  "hidden":false,
  "events":[],
  "title":"Rate your experience",   // question title
  "default_value":null,
  "file":null,
  "options":[1,10],
  "id":0
}

Above is an example of a 'Range' type of field. It allows a user to select a number between 1 and 10.

What fields are available for forms?

The following table contains details about all fields available via the Zenput Form Builder.

Fields GroupFieldJSON ValueData TypeDescription
LayoutSectionsectionNot applicableSection break
Important: Sections are not part of any report analysis.
InstructionsinstructionsNot applicableStatic instructions for end users
Important: Instructions are not part of any report analysis.
General QuestionsYes/NoyesnobooleanQuestion that can take either a yes or a no for an answer.
Important: The answer can also be N/A if the submission of such answer is enabled in the Zenput Form Builder. With yes/no questions the pass/fail option is always required. You can decide the pass/fail rating however you like.
TexttextString(unlimited)Adding a text question requires that the person who fills out the form adds in their own text.
Multiple ChoiceselectString(unlimited)This type of question is great if you need the user to select the best answer from various options. When you ask a question with multiple answer choices please first type the question in the Title box. Then, type in the various choices in the Options box. Keep in mind that you will need to separate each choice with a comma.
Numbernumberint(18)These types of questions require a number answer.
CheckboxcheckboxbooleanCheckbox widget value
Date/Timedatetimeint(18)(epoch in milliseconds) If you use this type of question, it will automatically capture the date. You can also capture the time by clicking on the checkbox that says “Date”. Below is what it looks like for the user.
Ratingrangeint(18)This type of question asks the user to rate an aspect of your business on a predetermined scale of your choice (ex: 1-10, 1-100).
Emailemailvarchar(100)This field asks the user to enter an email address. They can either type in the email address(es) manually, or click on the blue contact icon and select the address(es) from their address book. Note: Adding this field to a form will email a copy of the form submission to the email (s) added. If you want to turn off the emails, click on the 'Triggers' tab and uncheck the box labeled 'Email field'.
StopwatchstopwatchThis type of question lets a user start and stop a timer, as well as enter time manually if necessary. Normal Stopwatch: Choosing the ‘Stopwatch’ option performs exactly as you would expect: After the user presses the ‘Stopwatch’ button, a stopwatch will begin. When the user is done, they simply hit stop and the time will be saved. Manual: This stopwatch option makes the stopwatch act more like a time selector. (Example: A question asks “How long until you were greeted once entering the building?”) Rather than having the form submitter start and stop the stopwatch, they can simply enter the amount of time something took by setting the time manually. Note: Manual stopwatch must be enabled in the question options from the Zenput Form Builder.
MediaPhotoimagevarchar(255)(path) Use this with the Storage API to download media. This field asks that a user take a photo. Users will also be able to add notes describing the photo when necessary. Note: There is no maximum number of videos or pictures that can be uploaded for a particular form. However, there is currently a restriction that only allows the form submission upload to be up to 120mb. This will be many pictures, depending on the quality of the camera. A high-quality video that is just a few minutes long can easily exceed 120mb.
Signaturesignaturevarchar(255)(path) Use this with the Storage API to download media. This field allows a user to capture a signature while out in the field. Note: works best with auto-rotate off and in a horizontal position as opposed to vertical.
BarcodebarcodeBarcode/QR code scan (via a mobile device's camera) or capture (via the mobile device's keyboard)
Videovideovarchar(255)(path) Use this with the Storage API to download media. This field will allow a user to take a video and attach it to submission. Video can be added from a mobile device gallery or can be taken on the fly using the device's camera. A user will also have the ability to add notes to the video when necessary. Note: to watch video submissions you must be using the Web-App, these submissions are not available to view via the mobile device. There is no maximum number of videos or pictures that can be uploaded for a particular form. However, there is currently a restriction that only allows the form submission upload to be up to 120mb. This will be many pictures, depending on the quality of the camera. A high-quality video that is just a few minutes long can easily exceed 120mb.
Documentdocumentvarchar(255)(path) Use this with the Storage API to download media. Will ask users to upload/attach a PDF. DOC. or XLS files. Documents can be added from a user's gallery or drive where files are saved.
AdvancedFormulaformulaint(18)A formula will give a score based on how questions in the form are answered. A formula is calculated by SUM (addition) SUB (subtraction) AVG (average) or PCT (percentage). When setting up a formula, you simply select how you would like to calculate the score and select the questions you would like included in the calculation. In the case of multiple-choice and yes/no questions, you may also be asked to assign a value to the specific answer in order to calculate a score.
LocationaccountJSON objectLocation object that contains ID, name, etc. Will ask a user to select from a list of locations that have been uploaded to the company account. If the user's location-sharing is turned on, Zenput will automatically look for the nearest location using the user's GPS coordinates. If for some reason, the closest location does not automatically load, the submitter can start typing the location's name and Zenput will sort against all company locations.
Temperaturetemperatureint(18)Fahrenheit - API clients should always submit the temperature in Fahrenheit. To capture temperatures at your location we have a field where users can enter the temperature of what you would like them to capture. When setting up Temperature questions you can also "Enable the Pass/Fail range" to a predetermined Temp. range or a customer temp. range. Based on the response if you would like a dependent question to follow-up this response, you can also check the "Enable Dependent Questions" to display when it is a Pass, Fail, Pass or Fail, or Neutral.

Form Templates

Below is an example of a form template with one range question that can take values between 1 and 10.

{
  "fields":[        // a list of questions
    {
      "instructions":"",    // optional instructions show to a user
      "value":"",       // this value is filled in once submitted
      "metadata":null,
      "title_image":[],
      "type":"range",       // the type of question is it, i.e. number, text, etc
      "key":"",
      "hidden":false,
      "events":[],
      "title":"Rate your experience",   // question title
      "default_value":null,
      "file":null,
      "options":[1,10],
      "id":0
    }
  ],
  "smetadata":{                                     
        ...     // metadata about the form submission
  },
  "metadata":{          // metadata about the form template
    "rdbms_id":17763,       // the form template ID
    "company":{"id":1},
    "created_by":{
      "display_name":"John Mills",
      "id":1
    },
    "date_created":{
      "$date":1519246472626
    },
    "title":"Bathroom Cleanliness",
    "order":["0"],      // The order that the questions should appear
    "auto_increment_next_id":1,
    "is_creator_lock":true,
    "version":{"id":1.0}
  }
}

Form Submissions

The structure is the same as above, however, it has values that are filled in from the user along with other form submission metadata, which is smetadata.

{
  "success":true,
   "_id":{
      "$oid":"5a8ddca19820b50012b855a8" // the form submission ID
   },
   "fields":[
      {
         "title_image":[],
         "title":"Rate your experience",
         "hidden":false,
         "instructions":"",
         "options":[1,10],
         "metadata":null,
         "file":null,
         "events":[],
         "value":10,    // the answer (the user selected 10 on the scale)
         "key":"",
         "type":"range",
         "id":0,
         "default_value":null
      }
   ],
   "smetadata":{    // information regarding the user submitting
      "guid":"6-17763-1519246495889",
      "platform":"ios",
      "products":null,
      "time_to_complete":1483,  // milliseconds to complete form    
      "distance_to_account":null,   // distance from location (if a location field is present)
      "user_role":{
         "name":"General Manager",
         "id":603
      },
      "environment":"web",
      "date_created":{
         "$date":1519246495889
      },
      "company":{"id":1},
      "accounts":null,
      "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.167 Safari/537.36",
      "distribute_groups":[ // groups that the user is in
         {"id":2}
      ],
      "lat":37.7809995, // lattitude of user submitting
        "lon":-122.40696829999999, // longitude of user submitting
      "time_zone":"America/Los_Angeles",    // timezone of user submitting
      "date_modified":{
         "$date":1519246495889  // epoch date of last modification
      },
      "project":null,
      "account_tags":null,
      "created_by":{
         "id":6,
         "display_name":"John Mills"
      },
      "date_submitted":{
         "$date":1519246497907
      },
      "product_tags":null,
      "task":null,
      "date_completed":{
         "$date":1519246497372
      }
   },
   "status":200,
   "metadata":{
     ...        // same as the example above
   }
}

What’s Next

Try these endpoints out now!