Forms

What can you do with the forms endpoints?

The following list includes the actions that you can perform with the forms endpoints of the Zenput API.

List Form Templates: Get the properties of all existing form templates corresponding to your company.
Retrieve Form Template: Get the properties of a form template by providing an existing form template ID.
List Form Submissions: Get the properties of a form template and any corresponding form submissions by providing an existing form template ID.
Retrieve Form Submission: Get the properties of a form submission by providing an existing form submission ID.

What do you need to know about forms?

The following table contains concepts about forms.

Concept	Definition
Forms	Forms are the documents that users utilize to track specific activities.
Templates	Templates represent blank forms. That is, forms with fields without answers. Users set up templates in a web browser via the Zenput Form Builder.
Submissions	Submissions represent filled-out forms. That is, forms with fields and their answers. Users fill out versions of templates (blank forms) on a mobile device and then provide their answers within submissions (filled-out forms) via the Zenput Mobile App.
Fields	Fields correspond to the questions that users can select and configure in a form.

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 users can 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 Group	Field	JSON Value	Data Type	Description
Layout	Section	`section`	Not applicable	Section break Important: Sections are not part of any report analysis.
Layout	Instructions	`instructions`	Not applicable	Static instructions for users Important: Instructions are not part of any report analysis.
General Questions	Yes/No	`yesno`	boolean	Question 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.
	Text	`text`	String(unlimited)	Adding a text question requires that the person who fills out the form adds in their own text.
	Multiple Choice	`select`	String(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.
	Number	`number`	int(18)	These types of questions require a number answer.
	Checkbox	`checkbox`	boolean	Checkbox widget value
	Date/Time	`datetime`	int(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.
	Rating	`range`	int(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).
	Email	`email`	varchar(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'.
	Stopwatch	`stopwatch`		This 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.
Media	Photo	`image`	varchar(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.
	Signature	`signature`	varchar(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.
	Barcode	`barcode`		Barcode/QR code scan (via a mobile device's camera) or capture (via the mobile device's keyboard)
	Video	`video`	varchar(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.
	Document	`document`	varchar(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.
Advanced	Formula	`formula`	int(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.
	Location	`account`	JSON object	Location 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.
	Temperature	`temperature`	int(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
   }
}