# 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](https://www.navixy.com/docs/navixy-api/user-api/backend-api/resources/field-service/form/template) page.
* For description of `<form_field>` and `<field_value>`, see [Form fields and values](https://www.navixy.com/docs/navixy-api/user-api/backend-api/resources/field-service/form/field-types).
* Web API only allows attaching/filling out forms with tasks (check-in forms are created through Android/iOS tracker applications). See [Task form actions](https://www.navixy.com/docs/navixy-api/user-api/backend-api/resources/field-service/task/form/index) to use forms with tasks.

Find comprehensive information on form usage in our [instructions](https://www.navixy.com/docs/navixy-api/user-api/backend-api/guides/field-service-management/create-forms).

## Form object

```json
{
    "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](https://www.navixy.com/docs/navixy-api/user-api/backend-api/resources/field-service/form/field-types) objects.
* `created` - [date/time](https://www.navixy.com/docs/navixy-api/user-api/backend-api/..#data-types). 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](https://www.navixy.com/docs/navixy-api/user-api/backend-api/resources/field-service/form/field-types) objects as values. Can be null if form not filled.
  * `key` - string. Key used to link field and its corresponding value.
* `submitted` - [date/time](https://www.navixy.com/docs/navixy-api/user-api/backend-api/..#data-types). Date when form values last submitted.
* `submit_location` - location at which form values last submitted.

## Form file object

```json
{
    "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.navixy.com/file/dl/1/0/1g/01gw2j5q7nm4r92dytolzd6koxy9e38v.png/lala.jpg"
}
```

* `id` - int. File ID.
* `type` - [enum](https://www.navixy.com/docs/navixy-api/user-api/backend-api/..#data-types). Can be "image" or "file".
* `created` - [date/time](https://www.navixy.com/docs/navixy-api/user-api/backend-api/..#data-types). Date when file created.
* `uploaded` - [date/time](https://www.navixy.com/docs/navixy-api/user-api/backend-api/..#data-types). 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](https://www.navixy.com/docs/navixy-api/user-api/backend-api/..#data-types). 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

{% tabs %}
{% tab title="cURL" %}

```sh
curl -X POST 'https://api.eu.navixy.com/v2/form/read' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "id": 2}'
```

{% endtab %}

{% tab title="HTTP GET" %}

```http
https://api.eu.navixy.com/v2/form/read?hash=a6aa75587e5c59c32d347da438505fc3&id=2
```

{% endtab %}
{% endtabs %}

#### Response

```json
{
    "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.navixy.com/file/dl/1/0/1g/01gw2j5q7nm4r92dytolzd6koxy9e38v.png/lala.jpg"
    }]
}
```

* `value` - A [form object](#form-object).
* `files` - list of [form\_file objects](#form-file-object). 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](https://www.navixy.com/docs/navixy-api/user-api/backend-api/..#data-types) |

#### Examples

{% tabs %}
{% tab title="cURL" %}

```sh
curl -X POST 'https://api.eu.navixy.com/v2/form/download' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "id": 2, "format": "pdf"}'
```

{% endtab %}

{% tab title="HTTP GET" %}
{% code overflow="wrap" %}

```http
https://api.eu.navixy.com/v2/form/download?hash=a6aa75587e5c59c32d347da438505fc3&id=2&format=pdf
```

{% endcode %}
{% endtab %}
{% endtabs %}

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