Forms API

The forms API will allow you to query for form templates and submissions in Zenput. Below is a brief explanation of the concept of our 'Forms'.


Form Template	A blank form that is to be filled out by your users. This will show all the possible questions and associated metadata with that form
Form Submission	When a user completes a Form Template, it becomes a submission. This is what is filled out on the mobile device

Basic Form Template Structure

A form in its simplest form consists of 3 different top level pieces of information. The fields, which is an array of questions that was built with the form builder, metadata about the Form Template, and smetadata which contains information about who and where the form was submitted.

{
  "fields": [],		// an array of different questions
  "metadata": {},	// metadata about the Form Template
  "smetadata": {}	// metadata about the Form Submission
}

Basic Field (Question) Structure

Each field 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.

Below is a list of all the possible field types:


field type	length	description
account	JSON object	an account (location) object that contains id, name, etc.
text	(unlimited)	string
number	int(18)	number
select	(unlimited)	strings
checkbox	boolean	true, false, or null
datetime	int(18)	number (epoch in milliseconds)
yesno	boolean	true, false, or null
range	int(18)	number
email	varchar(100)	string
image	varchar(255)	string (url minus https://production-forms.storage.zenput.com)
video	varchar(255)	string (url minus https://production-forms.storage.zenput.com)
signature	varchar(255)	string (url minus https://production-forms.storage.zenput.com)
temperature	int(18)	number
formula	int(18)	number
instructions		no value - used to display info to the user
section		no value - used to display info to the user

Complete Form Template Structure

Below is an example of a Form Template with one question that is a range from 1-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}
  }
}

Complete Form Submission Structure

Continuing with the example from above, when a user submits a Form Template it becomes a Form Submission. The structure is the same as above, however it has values that are filled in from the user along with other submission metadata, nicknamed smetadata (see below)

{
  "success":true,
   "_id":{
      "$oid":"5a8ddca19820b50012b855a8" // the 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
   }
}