Forms Endpoints

Get access to Zenput forms data.

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

  • Details about all existing templates corresponding to your company
  • Details about a template and any corresponding submissions given an existing template ID
  • Details about a submission given an existing submission ID

Concepts on Forms

The following table contains concepts on forms.

Concept

Definition

Templates

Templates are blank versions of forms that end users can set up in a web browser (via the Zenput form builder).

Templates contain sets of blank fields. (The terms "field" and "question" refer to the same entity.)

Submissions

Submissions are filled-out versions of forms that end users can complete on a mobile device on the field.

Submissions contain sets of filled-out fields.

Forms Structure

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

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

Field 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.

The following table contains data regarding all fields.

Name

Type

Description

account

JSON object

an account (location) object that contains id, name, etc.

text

string(unlimited)

number

int(18)

select

string(unlimited)

checkbox

boolean

datetime

int(18)

(epoch in milliseconds)

yesno

boolean

range

int(18)

email

varchar(100)

image

varchar(255)

(path)

Use this with the Storage API to download media.

video

varchar(255)

(path)

Use this with the Storage API to download media.

signature

varchar(255)

(path)

Use this with the Storage API to download media.

document

varchar(255)

(path)

Use this with the Storage API to download media.

temperature

int(18)

Fahrenheit - API clients should always submit the temperature in Fahrenheit

formula

int(18)

instructions

no value - used to display info to the user

section

no value - used to display info to the user

Template Structure

Below is an example of a 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 submission
  },
  "metadata":{          // metadata about the template
    "rdbms_id":17763,       // the 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}
  }
}

Submission Structure

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

{
  "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
   }
}