Get Submissions

Get Form Submissions

/api/v1/forms/list/<template_id>

📘

Form Submissions are submitted by a user from a mobile device. A user sees a Form Template on their phone which turns into a Form Submission once our servers receive it.

Note that the sort order of form submissions returned is by date submitted descending.

parameter

description

template_id

(required) the ID of the template you want to get submissions for

start

(optional) where to start paginating (0 is default)

limit

(optional) - maximum of 100

date_start

(optional) - a starting date in the format of YYYYMMDD

date_end

(optional) - a starting date in the format of YYYYMMDD. If date_end is not included and date_start is, date_end defaults to today

use_utc_date_range

(optional: default=True) - True or False.

True: date_start and date_end ranges for the query are compared to the UTC datetime for the submission.
False: date_start and date_end ranges for the query are compared to the localized submission date.

  • For example, if 3 stores have a closing form that is submitted at 11pm (local) across multiple time zones, you would want to use use_utc_date_range=False to get all three submissions for the desired day.

count

(optional:default=False) True or False
True A count of the number of submissions is included as a top level key in the api response.
False Count is not included

Example Query

curl --header "X-API-TOKEN: <API Token>" \
    'https://www.zenput.com/api/v1/forms/list/<template_id>?output=json'

Example Response

Get an individual Form Submission

/api/v1/forms/get/

📘

This endpoint allows you to pull information for an individual submission in JSON or HTML formats.

parameter

description

output

(optional) json (default) or html or pdf_url (returns the link to the pre-generated submission pdf)

expanded_metadata

(optional) true or false (default)

Example Query to get JSON

curl --header "X-API-TOKEN: <API_TOKEN>" \
    'https://www.zenput.com/api/v1/forms/get/<submission_id>?output=json'

Example Response

{
   "success":true,
   "status":200,
   "_id":{
      "$oid":"5a8ddca19820b50012b855a8"
   },
   "fields":[
      {
         "events":[],
         "title":"Rate your experience",
         "options":[1,10],
         "default_value":null,
         "value":10,
         "key":"",
         "file":null,
         "instructions":"",
         "metadata":null,
         "type":"range",
         "id":0,
         "hidden":false,
         "title_image":[]
      }
   ],
   "can_edit":true,
   "sort_fields":{
      "0":{
         "value":10
      }
   },
   "deleted":0,
   "metadata":{
      "title":"Bathroom Cleanliness",
      "auto_increment_next_id":1,
      "company":{
         "id":1
      },
      "is_copy_enabled":false,
      "is_creator_lock":true,
      "deleted":false,
      "created_by":{
         "display_name":"John Mills",
         "id":1
      },
      "version":{"id":1},
      "rdbms_id":17763,
      "is_force_camera":false,
      "order":["0"],
      "is_secure":false,
      "date_created":{
         "$date":1519246472626
      }
   },
   "smetadata":{
      "date_completed":{
         "$date":1519246497372
      },
      "date_completed_local":{
         "$date":1519174495000
      },
      "project":null,
      "company":{"id":1},
      "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",
      "account_tags":null,
      "lon":-122.40696829999999,
      "time_to_complete":1483,
      "environment":"web",
      "product_tags":null,
      "guid":"6-17763-1519246495889",
      "task":null,
      "created_by":{
         "display_name":"John Mills",
         "id":6
      },
      "time_zone":"America/Los_Angeles",
      "distance_to_account":null,
      "products":null,
      "platform":"unknown",
      "lat":37.7809995,
      "date_modified":{
         "$date":1519246495889
      },
      "distribute_groups":[
         {"id":2}
      ],
      "date_submitted":{
         "$date":1519246497907
      },
      "date_submitted_local":{
         "$date":1519174675000
      },
     "date_created_local":{
            "$date": 1519174495000
        },
      "user_role":{
         "name":"General Manager",
         "id":603
      },
      "accounts":null,
      "date_created":{
         "$date":1519246495889
      },
      "date_created_local":{
            "$date": 1519174495000
        }
   }
}

Get expanded metadata about related tasks & projects

curl --header "X-API-TOKEN: <API_TOKEN>" \
    'https://www.zenput.com/api/v1/forms/get/<submission_id>?expanded_metadata=true'

Example response

{
  "fields": [...],
  "metadata": {...},
  "smetadata": {...},
  "expanded_metadata": {
        "tasks": [{     // tasks that were generated from this submission
            "date_due": null,
            "assignee": {
                "first_name": "John",
                "last_name": "Mills",
                "display_name": "John Mills",
                "id": 13
            },
            "fulfillment": null,
            "id": 52,
            "is_closed": false,
            "title": "test_all_submissions",
            "date_start": {"$date": 1520633728000},
            "lon": null,
            "source": {     // information about how this was triggered
                "rule": {
                    "id": 27,"title": "test_all_submissions"
                },
                "reason": "Any submission.",
                "form_submission": {
                    "_id": {"$oid": "5aa3077f8c468d0d100d5212"},
                    "smetadata": {
                        "date_submitted": {"$date": 1520633727241},
                        "created_by": {
                            "display_name": "John Mills",
                            "id": 13
                        }
                    },
                    "metadata": {
                        "rdbms_id": 1, "title": "Bathroom Cleanliness"
                    }
                },
                "type": "rule_event",
                "event": {"id": 71}
            },
            "followers": [],
            "reply": {
                "type": "form_submission",
                "form_template": {
                    "id": 27, "title": "Bathroom Cleanliness"
                }
            },
            "status": {
                "type": "open","name": "Incomplete"
            },
            "description": null,
            "reporter": {
                "first_name": "Testy",
                "last_name": "McGee",
                "display_name": "Testy McGee",
                "id": 2
            },
            "date_submitted": null,
            "company": {"id": 1},
            "is_active": true,
            "lat": null,
            "account": {
                "external_key": "3",
                "phone": null,
                "address": "1020 Market Street",
                "lat": 37.782054,
                "id": 3,
                "city": "San Francisco",
                "name": "Show Dogs",
                "country": "US",
                "lon": -122.410932,
                "zipcode": "94102",
                "state": "CA",
                "email": null
            },
            "date_modified": {"$date": 1520633728000},
            "time_zone": "America/Los_Angeles",
            "project": null,
            "date_created": {"$date": 1520633728273},
            "title_image": []
        }],
        "project": {    // if this form was part of a project associated metadata lives here
            "date_start_naive": "2018-03-09T00:00:00",
            "tasks_form_template": {
                "id": xxxx
            },
            "date_created": {
                "$date": 1520503233000
            },
            "id": 120639,
            "parent_project": {
                "date_start_naive": null,
                "tasks_form_template": {
                    "id": 10413
                },
                "date_created": {
                    "$date": 1496929867000
                },
                "is_started": true,
                "id": 30631,
                "parent_project": null,
                "created_user": {
                    "last_name": "Mills",
                    "first_name": "John",
                    "id": 13,
                    "display_name": "John Mills"
                },
                "recurring": {
                    "queue_create_data": null,
                    "is_system": false,
                    "rrule": {
                        "dtstart": {
                            "$date": 1496916000000
                        },
                        "interval": 1,
                        "custom_attrs": {
                            "dtstart_naive": "2017-06-09T00:00:00",
                            "date_start": {
                                "$date": 1496829600000
                            },
                            "set_min_start": true,
                            "date_start_naive": "2017-06-08T00:00:00"
                        },
                        "byweekday": [4],
                        "frequency": 2
                    },
                    "id": 1179,
                    "is_active": true
                },
                "followers": [],
                "date_start": null,
                "company": {
                    "name": "Zenput",
                    "id": 1
                },
                "date_modified": {"$date": 1496929867000},
                "date_due_naive": null,
                "is_auto_archive": true,
                "is_active": true,
                "date_due": null,
                "tasks": [],
                "title": "Bathroom Inspection",
                "description": null,
                "create_tasks_data": {
                    "title_image": [],
                    "account_tag": null,
                    "reply": {
                        "form_template": {
                            "title": "Bathroom Inspection",
                            "id": 1
                        },
                        "type": "form_submission"
                    },
                    "days_after": "4",
                    "distribute_group": {
                        "name": "California",
                        "id": 1
                    },
                    "version": {"id": 1},
                    "time_frame": {
                        "start": "00:00",
                        "end": "23:59"
                    },
                    "user_role": {
                        "name": "General Manager",
                        "id": 389
                    },
                    "due_type": "between"
                }
            },
            "created_user": {
                "last_name": "Mills",
                "first_name": "John",
                "id": 13,
                "display_name": "John Mills"
            },
            "recurring": null,
            "followers": [],
            "date_start": {"$date": 1520575200000},
            "company": {
                "name": "Zenput", "id": 1
            },
            "date_modified": {
                "$date": 1520503262000
            },
            "date_due_naive": "2018-03-09T23:59:59",
            "is_auto_archive": true,
            "is_active": true,
            "date_due": {"$date": 1520661540000},
            "tasks_data": { // statuses of the other tasks in this project
                "num_tasks": 3,
                "num_tasks_closed": 1
            },
            "tasks": [],
            "title": "Bathroom Inspection",
            "description": null,
            "create_tasks_data": {  // how this task is generated by Zenput
                "title_image": [],
                "account_tag": null,
                "reply": {
                    "form_template": {
                        "title": "Bathroom Inspection",
                        "id": 1
                    },
                    "type": "form_submission"
                },
                "days_after": "4",
                "distribute_group": {
                    "name": "California",
                    "id": 1
                },
                "time_frame": {
                    "start": "00:00",
                    "end": "23:59"
                },
                "user_role": {
                    "name": "General Manager",
                    "id": 389
                },
                "due_type": "between"
            }
        }
    }
}