Form

Attach a form to a task, read it, and download it.

These operations attach a form to a task, read it back, and download it. A task carrying a form cannot be completed until the form is submitted, which is how a job is made to produce a record rather than just a completion.

Forms are filled by field employees in the Mobile Tracker App, for Android and iOS. This API attaches and manages them.

For the field and value structures, see Form fields and values. task/form/list is the exception on this page: it returns forms of every kind, not only task forms.

API actions

API base path: /task/form.

Required sub-user rights: task_update.

Attach form to task

post

/task/form/create

Attach a new form to an existing task or checkpoint. A form is always created from a form template.

Allowed while the task is unassigned, assigned or arrived. A sub-user with the completed_form_update right may also act on a done, failed or delayed task. Anything else returns error 255.

Also accepts GET with the same parameters as query-string values.

Requires the task_update right.

Authorizations

AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Body

task_idinteger · min: 1Required

ID of the task or checkpoint to attach the form to.

template_idinteger · min: 1Required

ID of the form template to build the form from.

Responses

200

Form attached

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

409

Error 247: the task already has a form attached.

application/json

default

Error response object

application/json

post/task/form/create

POST /v2/task/form/create HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "task_id": 1,
  "template_id": 1
}

{
  "success": true
}

Errors

These errors come in addition to the general error codes:

201 - Not found in the database - if there is no task or template with such an ID, or task has the "route" type.
247 - Entity already exists - if task already has form attached to it.
255 - Invalid task state - if current task state is not unassigned, assigned or arrived (plus done, failed, and delayed for users with completed_form_update right).

All form data will be lost!

Required sub-user rights: task_update.

Delete task form

post

/task/form/delete

Detach a form from its task. All data entered in the form is lost.

Allowed while the task is unassigned, assigned or arrived. Anything else returns error 255.

Also accepts GET with the same parameters as query-string values.

Requires the task_update right.

Authorizations

AuthorizationstringRequired

Body

task_idinteger · min: 1Required

ID of the task the form is attached to.

Responses

200

Form deleted

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

default

Error response object

application/json

post/task/form/delete

POST /v2/task/form/delete HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 13

{
  "task_id": 1
}

{
  "success": true
}

Errors

These errors come in addition to the general error codes:

201 - Not found in the database - if there is no task with such an ID, or task has the "route" type, or it has no form attached.
255 - Invalid task state - if current task state is not unassigned, assigned or arrived.

Download task form

post

/task/form/download

Return the form attached to a task rendered as a file.

The response is the file itself, not a JSON envelope.

Also accepts GET with the same parameters as query-string values.

Authorizations

AuthorizationstringRequired

Body

task_idinteger · min: 1Required

ID of the task.

formatstring · enumRequired

Format of the downloaded file.

Possible values:

Responses

200

The rendered form file

string · binaryOptional

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

default

Error response object

application/json

post/task/form/download

POST /v2/task/form/download HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "task_id": 1,
  "format": "xlsx"
}

binary

Errors

These errors come in addition to the general error codes:

201 - Not found in the database - if task does not exist or does not have attached form.

In addition to the data on the forms, the list contains data on the objects related to each form: tracker, vehicle, employee and task.

List forms

post

/task/form/list

List forms created from a given template, or belonging to given tasks, with the related tracker, vehicle, employee and task for each.

This is the one form operation that is not restricted to task forms.

include_unsubmitted is the only required parameter. ascending is not required, and a request carrying only include_unsubmitted succeeds.

Giving neither template_id nor task_ids is not rejected, but the list comes back empty, so one of them is needed in practice.

Also accepts GET with the same parameters as query-string values.

Authorizations

AuthorizationstringRequired

Body

include_unsubmittedbooleanRequired

Whether to include forms that have not been submitted yet.

template_idinteger · min: 1Optional

Optional. Return forms built from this template.

task_idsinteger[] · min: 1 · max: 5000Optional

Optional. Return forms belonging to these tasks. Between 1 and 5000 IDs.

order_bystring · enumOptional

Optional. Default submitted. Field to sort the list by.

Possible values:

ascendingbooleanOptional

Optional. Default true. Sort direction.

offsetintegerOptional

Optional. Default 0. Offset into the results, for pagination.

limitinteger · max: 100000Optional

Optional. Default 10000, maximum 100000. Number of forms to return.

Responses

200

Matching forms

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

countintegerOptional

Total number of forms matching the query.

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

404

Error 204: no form template with this ID belongs to the authorized user.

application/json

default

Error response object

application/json

post/task/form/list

POST /v2/task/form/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 798

{
  "include_unsubmitted": true,
  "template_id": 1,
  "task_ids": [
    1
  ],
  "order_by": "task_id",
  "ascending": true,
  "filters": {
    "employee_full_name": "text",
    "form_description": "text",
    "form_label": "text",
    "submit_address": "text",
    "task_id": 1,
    "task_address": "text",
    "task_label": "text",
    "tracker_label": "text",
    "vehicle_label": "text"
  },
  "submit_period": {
    "from": "2026-08-24 09:00:00",
    "to": "2026-08-24 09:00:00"
  },
  "task_creation_period": {
    "from": "2026-08-24 09:00:00",
    "to": "2026-08-24 09:00:00"
  },
  "task_from_period": {
    "from": "2026-08-24 09:00:00",
    "to": "2026-08-24 09:00:00"
  },
  "task_to_period": {
    "from": "2026-08-24 09:00:00",
    "to": "2026-08-24 09:00:00"
  },
  "task_arrival_period": {
    "from": "2026-08-24 09:00:00",
    "to": "2026-08-24 09:00:00"
  },
  "task_completion_period": {
    "from": "2026-08-24 09:00:00",
    "to": "2026-08-24 09:00:00"
  },
  "offset": 1,
  "limit": 1
}

{
  "success": true,
  "count": 1,
  "list": [
    {
      "form": {
        "id": 1,
        "label": "text",
        "description": "text",
        "fields": [
          {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ],
        "created": "text",
        "submit_in_zone": true,
        "task_id": null,
        "checkin_id": null,
        "tracker_id": null,
        "template_id": null,
        "template_version": null,
        "values": null,
        "submitted": null,
        "submit_location": {
          "lat": 1,
          "lng": 1,
          "address": "text"
        }
      },
      "task": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "employee": null,
      "tracker": null,
      "vehicle": null,
      "submit_places": {
        "location": {
          "lat": 1,
          "lng": 1,
          "address": "text"
        },
        "places": [
          {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ],
        "zones": [
          {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ]
      }
    }
  ]
}

Errors

These errors come in addition to the general error codes:

204 - Not found - if there is no form template with such ID belonging to authorized user.
General types of errors.

current sub-user.

Read task form

post

/task/form/read

Return the form attached to a task, together with every file associated with its fields, submitted or not.

value is null when the task has no form.

Also accepts GET with the same parameters as query-string values.

Authorizations

AuthorizationstringRequired

Body

task_idinteger · min: 1Required

ID of the task.

Responses

200

The form and its files

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

default

Error response object

application/json

post/task/form/read

POST /v2/task/form/read HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 13

{
  "task_id": 1
}

{
  "success": true,
  "value": {
    "id": 1,
    "label": "text",
    "description": "text",
    "fields": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "created": "text",
    "submit_in_zone": true,
    "task_id": null,
    "checkin_id": null,
    "tracker_id": null,
    "template_id": null,
    "template_version": null,
    "values": null,
    "submitted": null,
    "submit_location": {
      "lat": 1,
      "lng": 1,
      "address": "text"
    }
  },
  "files": [
    {
      "id": 1,
      "storage_id": 1,
      "user_id": 1,
      "type": "image",
      "created": "text",
      "uploaded": null,
      "name": "text",
      "size": 1,
      "mime_type": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "state": "created",
      "download_url": null,
      "bindings": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "previews": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ]
    }
  ]
}

Errors

These errors come in addition to the general error codes:

201 - Not found in the database - if there is no task with such an ID, or task assigned to tracker unavailable to\

Form

API actions

Attach form to task

Errors

Delete task form

Errors

Download task form

Errors

List forms

Errors

Read task form

Errors

More in this section

Task form files

Task form values