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

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

## 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](/docs/navixy-api/user-api/backend-api/resources/field-service/form/field-types.md) objects.
* `created` - [date/time](/docs/navixy-api/user-api/backend-api.md#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](/docs/navixy-api/user-api/backend-api/resources/field-service/form/field-types.md) objects as values. Can be null if form not filled.
  * `key` - string. Key used to link field and its corresponding value.
* `submitted` - [date/time](/docs/navixy-api/user-api/backend-api.md#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](/docs/navixy-api/user-api/backend-api.md#data-types). Can be "image" or "file".
* `created` - [date/time](/docs/navixy-api/user-api/backend-api.md#data-types). Date when file created.
* `uploaded` - [date/time](/docs/navixy-api/user-api/backend-api.md#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](/docs/navixy-api/user-api/backend-api.md#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](/docs/navixy-api/user-api/backend-api.md#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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://navixy.com/docs/navixy-api/user-api/backend-api/resources/field-service/form/index.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.