#About forms

Forms are used to provide additional information, such as the user's name, phone, delivery date, etc. upon task completion or check-in from iOS/Android mobile tracker app.

Forms can be attached to tasks. If a form attached to a task, this task cannot be completed without submitting the form.

Each form must be created from a template. Read more on the Templates page.
For description of <form_field> and <field_value>, see Form fields and values.
Web API only allows attaching/filling out forms with tasks (check-in forms are created through Android/iOS tracker applications). See Task form actions to use forms with tasks.

Find comprehensive information on form usage in our instructions.

#Form object

{
    "id": 2,
    "label": "Order form",
    "fields": [
      {
        "id": "111-aaa-whatever",
        "label": "Name",
        "description": "Your full name",
        "required": true,
        "min_length": 5,
        "max_length": 255,
        "type": "text"
      }
    ],
    "created": "2017-03-15 12:36:27",
    "submit_in_zone": true,
    "task_id": 1,
    "template_id": 1,
    "description": "",
    "template_version": null,
    "tracker_id": 14,
    "checkin_id": null,
    "values": {
      "111-aaa-whatever": {
        "type": "text",
        "value": "John Doe"
      }
    },
    "submitted": "2017-03-21 18:40:54",
    "submit_location": {
      "lat": 11.0,
      "lng": 22.0,
      "address": "Wall Street, NY"
    }
}

id - int. Form unique ID.
label - string. User-defined form label, from 1 to 100 characters.
fields - array of multiple form_field objects.
created - date/time. Date when this form created (or attached to the task). The read-only field.
submit_in_zone - boolean. If true, form can be submitted only in task zone.
task_id - int. An ID of the task to which this form attached.
template_id - int. An ID of the form template on which this form based. Can be null if template deleted.
values - a map with field IDs as keys and field_value objects as values. Can be null if form not filled.
- key - string. Key used to link field and its corresponding value.
submitted - date/time. Date when form values last submitted.
submit_location - location at which form values last submitted.

#Form file object

{
    "id": 16,
    "storage_id": 1,
    "user_id": 12203,
    "type": "image",
    "created": "2017-09-06 11:54:28",
    "uploaded": "2017-09-06 11:55:14",
    "name": "lala.jpg",
    "size": 72594,
    "mime_type": "image/png",
    "metadata": <metadata_object>,
    "state": "uploaded",
    "download_url": "https://static.mergroup.be/file/dl/1/0/1g/01gw2j5q7nm4r92dytolzd6koxy9e38v.png/lala.jpg"
}

id - int. File ID.
type - enum. Can be "image" or "file".
created - date/time. Date when file created.
uploaded - date/time. Date when file uploaded. Can be null if file not yet uploaded.
name - string. A filename.
size - int. Size in bytes. If file not uploaded, show maximum allowed size for the upload.
metadata - nullable metadata object.
state - enum. Can be "created" | "in_progress" | "uploaded" | "deleted".
download_url - string. Actual URL at which file is available. Can be null if file not yet uploaded.

#API actions

API path: /form.

#read

Gets form by an ID.

#Parameters

name	description	type
id	ID of the form.	int

#Examples

curl -X POST 'https://api.mergroup.be/form/read' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "id": 2}'

https://api.mergroup.be/form/read?hash=a6aa75587e5c59c32d347da438505fc3&id=2

#Response

{
    "success": true,
    "value": {
         "id": 2,
         "label": "Order form",
         "fields": [
           {
             "id": "111-aaa-whatever",
             "label": "Name",
             "description": "Your full name",
             "required": true,
             "min_length": 5,
             "max_length": 255,
             "type": "text"
           }
         ],
         "created": "2017-03-15 12:36:27",
         "submit_in_zone": true,
         "task_id": 1,
         "template_id": 1,
         "values": {
           "111-aaa-whatever": {
             "type": "text",
             "value": "John Doe"
           }
         },
         "submitted": "2017-03-21 18:40:54",
         "submit_location": {
           "lat": 11.0,
           "lng": 22.0,
           "address": "Wall Street, NY"
         }
    },
    "files": [{
      "id": 16,
      "storage_id": 1,
      "user_id": 12203,
      "type": "image",
      "created": "2017-09-06 11:54:28",
      "uploaded": "2017-09-06 11:55:14",
      "name": "lala.jpg",
      "size": 72594,
      "mime_type": "image/png",
      "metadata": {
       "orientation":  1
      },
      "state": "uploaded",
      "download_url": "https://static.mergroup.be/file/dl/1/0/1g/01gw2j5q7nm4r92dytolzd6koxy9e38v.png/lala.jpg"
    }]
}

value - A form object.
files - list of form_file objects. Files used in values of this form. Can be null or empty.

#Errors

201 – Not found in the database - if there is no form with such an ID.

#download

Downloads form as a file by an ID.

#Parameters

name	description	type
id	ID of the form.	int
format	File format. Can be `pdf` or `xlsx`.	enum

#Examples

curl -X POST 'https://api.mergroup.be/form/download' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "id": 2, "format": "pdf"}'

https://api.mergroup.be/form/download?hash=a6aa75587e5c59c32d347da438505fc3&id=2&format=pdf

#Response

Regular file download, or JSON with an error.

#Errors

201 – Not found in the database - if there is no form with such an ID.