Task

A job assigned to a tracked device, completed by visiting a place and meeting its conditions.

A task is a job assigned to a tracked device. It completes when that device reaches the task's checkpoint at the right time and meets whatever else the task requires, such as filling a form or staying in the task's zone for a set period. Otherwise it fails, or completes with warnings.

A task assigned to a device running the Mobile Tracker App, for Android or iOS, is visible to the person carrying it, who is also notified when a task is assigned or changed.

Tasks that repeat are scheduled rather than created one by one, and tasks that must be done in sequence are grouped into a route. For a walkthrough, see how to create and assign tasks.

Task object

Custom field values are keyed by custom field ID as a string. See entity/fields. For the attached form, see the form object.

The conditions parameter of task/list takes search conditions.

API actions

API base path: /task.

Operations that list no errors of their own return only the general error codes.

Required sub-user rights: task_update.

Assign task

post

/task/assign

Assign a task to a tracker, reassign it to a different one, or leave it unassigned.

Pass tracker_id as null, or leave it out, to unassign.

Only a task in unassigned or assigned state can be changed. 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 to assign.

tracker_idinteger · min: 1 · nullableOptional

ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked. Null leaves the task assigned to no one.

Responses

200

Task assigned

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

402

Error 236: the tracker's plan does not allow tasks.

application/json

403

Error 208: the tracker exists but is blocked, normally because its tariff ended.

application/json

404

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

application/json

default

Error response object

application/json

post/task/assign

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

{
  "task_id": 1,
  "tracker_id": null
}

{
  "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).
204 - Entity not found (if there is no tracker with such ID belonging to authorized user).
208 - Device blocked (if tracker exists but was blocked due to tariff restrictions or some other reason).
255 - Invalid task state (if current task state is not "unassigned" or "assigned").
236 - Feature unavailable due to tariff restrictions (if device's tariff does not allow usage of tasks).

Required sub-user rights: task_update.

Convert task batch

post

/task/batch_convert

Parse a tab-delimited batch of tasks and return them checked, with per-row errors. Creates nothing.

Give either batch or file_id. A request with neither returns error 7 with the message "The 'batch' or 'file_id' parameter must be specified".

Recognised column names are label, from, to, address, lat, lng, radius, description, external_id, performer, max_delay, min_stay_duration and min_arrival_duration. Any other column name is read as a custom field ID and ignored if no such field exists.

When only from is given for a row, to is set to from plus default_duration.

Requires the task_update right.

Authorizations

AuthorizationstringRequired

Body

batchstringOptional

Batch of tab-delimited tasks.

file_idstringOptional

Preloaded file ID, as an alternative to batch.

fieldsstring[]Optional

Optional. Column names, in order. Defaults to ["label", "from", "to", "address", "lat", "lng", "description", "min_stay_duration", "max_delay", "min_arrival_duration"].

geocoderstringOptional

Geocoder type to use for resolving addresses.

default_radiusintegerOptional

Optional. Default 100. Zone radius in metres for a row that gives no radius.

default_max_delayintegerOptional

Optional. Default 0. Maximum delay in minutes for a row that gives no max_delay.

default_durationintegerOptional

Optional. Default 60. Task duration in minutes, used to derive to from from.

default_min_stay_durationintegerOptional

Optional. Default 0. Minimum stay in minutes for a row that gives no min_stay_duration.

location_check_modestring · enumOptional

Optional. Default entity_location. How to match a row to a place. With entity_location, vehicle_ids is ignored.

Possible values:

employee_idsinteger[]Optional

Optional. Employees to distribute the tasks between automatically.

vehicle_idsinteger[]Optional

Optional. Vehicles to distribute the tasks between automatically. Ignored when location_check_mode is entity_location.

Responses

200

The checked batch

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

limit_exceededbooleanOptional

true if the given batch was constrained by a limit.

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/batch_convert

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

{
  "batch": "text",
  "file_id": "text",
  "fields": [
    "text"
  ],
  "geocoder": "text",
  "default_radius": 1,
  "default_max_delay": 1,
  "default_duration": 1,
  "default_min_stay_duration": 1,
  "location_check_mode": "no_check",
  "employee_ids": [
    1
  ],
  "vehicle_ids": [
    1
  ]
}

{
  "success": true,
  "list": [
    {
      "id": 1,
      "user_id": 1,
      "tracker_id": null,
      "location": {
        "lat": 1,
        "lng": 1,
        "address": "text",
        "radius": 1
      },
      "label": "text",
      "description": "text",
      "creation_date": "text",
      "from": "2026-08-24 09:00:00",
      "to": "2026-08-24 09:00:00",
      "external_id": null,
      "status": "unassigned",
      "status_change_date": "text",
      "max_delay": 1,
      "min_stay_duration": 1,
      "min_arrival_duration": 1,
      "arrival_date": null,
      "stay_duration": 1,
      "origin": "manual",
      "tags": [
        1
      ],
      "type": "task",
      "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"
        }
      },
      "form_template_id": 1,
      "fields": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "files": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "errors": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "limit_exceeded": true
}

Count tasks

post

/task/count

Return the total number of tasks belonging to the current user.

Callable with an empty body. Also accepts GET.

Authorizations

AuthorizationstringRequired

Responses

200

The count

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

countintegerOptional

Number of tasks.

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/count

POST /v2/task/count HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "count": 1
}

id is assigned by the server and is always unique, so task/create called twice with identical parameters creates two tasks that differ only by their ID. There is no deduplication. If a task has to correspond to a record in an external system, store the ID this call returns against that record, because it is the only way to change or delete the right task later.

For the external_id_counts field in the response, see the task/route/create method description.

Required sub-user rights: task_update.

Create task

post

/task/create

Create a task, and return its ID.

to is required and cannot be in the past, and from cannot be after to. Both rules are checked before anything else and report task.to or task.from rather than a top-level parameter.

Setting tracker_id assigns the task to the employee associated with that tracker and starts it in assigned state. Leaving it out starts the task unassigned.

Each call creates a new task even when the parameters are identical, because the ID is generated by the server. If a task has to stay tied to a record in an external system, keep the returned ID, or use external_id.

Requires the task_update right.

Authorizations

AuthorizationstringRequired

Body

create_formbooleanOptional

Optional. Default false, for backward compatibility. When true, the form_template_id inside task is read and a form is created from that template.

Responses

200

The created task

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

idintegerOptional

ID of the new task.

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

402

Error 236: the tracker's plan does not allow tasks.

application/json

default

Error response object

application/json

post/task/create

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

{
  "task": {
    "id": 1,
    "tracker_id": null,
    "location": {
      "lat": 1,
      "lng": 1,
      "address": "text",
      "radius": 1
    },
    "label": "text",
    "description": "text",
    "from": "2026-08-24 09:00:00",
    "to": "2026-08-24 09:00:00",
    "external_id": null,
    "status": "unassigned",
    "status_change_date": "text",
    "max_delay": 1,
    "min_stay_duration": 1,
    "min_arrival_duration": 1,
    "origin": "manual",
    "tags": [
      1
    ],
    "type": "task",
    "form": {
      "id": 1,
      "label": "text",
      "description": "text",
      "fields": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "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"
      }
    },
    "form_template_id": 1,
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "create_form": true
}

{
  "success": true,
  "id": 1,
  "external_id_counts": [
    {
      "external_id": "text",
      "count": 1
    }
  ]
}

Errors

These errors come in addition to the general error codes:

201 - Not found in the database (if task.tracker_id is not null and belongs to nonexistent tracker).
236 - Feature unavailable due to tariff restrictions (if device's tariff does not allow usage of tasks).

Required sub-user rights: task_update.

Delete task

post

/task/delete

Delete a task by ID.

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 to delete.

Responses

200

Task 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/delete

POST /v2/task/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).

List tasks

post

/task/list

List the tasks of the current user, with filtering, sorting and pagination.

A parameter left out or set to null is simply not used as a filter.

Callable with an empty body. Also accepts GET with the same parameters as query-string values.

Authorizations

AuthorizationstringRequired

Body

external_idstring · max: 100Optional

Optional. External task ID to search for. Up to 100 characters.

trackersinteger[]Optional

Optional. IDs of the trackers the tasks are assigned to. Must not contain duplicates.

fromstringOptional

Optional. Include tasks that are actual after this date.

Example: 2026-08-24 09:00:00

tostringOptional

Optional. Include tasks that are actual before this date.

Example: 2026-08-24 09:00:00

filterstring · max: 100Optional

Optional. Filter over all built-in and custom fields, up to 100 characters. Used together with conditions: both must match for a task to be returned.

filtersstring[]Optional

Optional. Filters for task label, description or address.

tag_idsinteger[]Optional

Optional. Restrict to tasks carrying these tag IDs.

sortstring[]Optional

Optional. Sort options, each a property and direction such as status=asc. Sortable properties: id, employee (full name, or the tracker label when there is no employee), status, label, location (the address), from, to, status_change_date, arrival_date, stay_duration, description, external_id, and form (the form label).

offsetintegerOptional

Optional. Default 0. Offset into the found tasks, for pagination.

limitinteger · max: 100000Optional

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

Responses

200

Matching tasks

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

countintegerOptional

Total number of tasks found, ignoring pagination.

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/list

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

{
  "external_id": "text",
  "statuses": [
    "unassigned"
  ],
  "trackers": [
    1
  ],
  "from": "2026-08-24 09:00:00",
  "to": "2026-08-24 09:00:00",
  "conditions": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "filter": "text",
  "filters": [
    "text"
  ],
  "tag_ids": [
    1
  ],
  "location": {
    "lat": 1,
    "lng": 1,
    "radius": 1
  },
  "sort": [
    "text"
  ],
  "offset": 1,
  "limit": 1
}

{
  "success": true,
  "list": [
    {
      "id": 1,
      "user_id": 1,
      "tracker_id": null,
      "location": {
        "lat": 1,
        "lng": 1,
        "address": "text",
        "radius": 1
      },
      "label": "text",
      "description": "text",
      "creation_date": "text",
      "from": "2026-08-24 09:00:00",
      "to": "2026-08-24 09:00:00",
      "external_id": null,
      "status": "unassigned",
      "status_change_date": "text",
      "max_delay": 1,
      "min_stay_duration": 1,
      "min_arrival_duration": 1,
      "arrival_date": null,
      "stay_duration": 1,
      "origin": "manual",
      "tags": [
        1
      ],
      "type": "task",
      "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"
        }
      },
      "form_template_id": 1,
      "fields": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "files": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ]
    }
  ],
  "count": 1
}

Read task

post

/task/read

Return a task, a checkpoint, or a route with its checkpoints, by ID.

Which of the three you get depends on what the ID belongs to. checkpoints is present only when the ID is a route.

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

Authorizations

AuthorizationstringRequired

Body

task_idinteger · min: 1Required

ID of the task, route or checkpoint.

Responses

200

The task, checkpoint or route

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/read

POST /v2/task/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,
    "user_id": 1,
    "tracker_id": null,
    "location": {
      "lat": 1,
      "lng": 1,
      "address": "text",
      "radius": 1
    },
    "label": "text",
    "description": "text",
    "creation_date": "text",
    "from": "2026-08-24 09:00:00",
    "to": "2026-08-24 09:00:00",
    "external_id": null,
    "status": "unassigned",
    "status_change_date": "text",
    "max_delay": 1,
    "min_stay_duration": 1,
    "min_arrival_duration": 1,
    "arrival_date": null,
    "stay_duration": 1,
    "origin": "manual",
    "tags": [
      1
    ],
    "type": "task",
    "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"
      }
    },
    "form_template_id": 1,
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "files": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ]
  },
  "checkpoints": [
    {
      "id": 1,
      "user_id": 1,
      "tracker_id": null,
      "location": {
        "lat": 1,
        "lng": 1,
        "address": "text",
        "radius": 1
      },
      "label": "text",
      "description": "text",
      "creation_date": "text",
      "from": "2026-08-24 09:00:00",
      "to": "2026-08-24 09:00:00",
      "external_id": null,
      "status": "unassigned",
      "status_change_date": "text",
      "max_delay": 1,
      "min_stay_duration": 1,
      "min_arrival_duration": 1,
      "arrival_date": null,
      "stay_duration": 1,
      "origin": "manual",
      "tags": [
        1
      ],
      "type": "task",
      "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"
        }
      },
      "form_template_id": 1,
      "fields": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "files": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "parent_id": 1,
      "order": 1
    }
  ]
}

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

Required sub-user rights: task_update.

Convert task to checkpoint

post

/task/transmute

Convert a task into a checkpoint of an existing route.

The checkpoint is inserted at order, and any checkpoint already at that position, along with everything after it, shifts one place right.

Only a task in unassigned or assigned state can be changed. Anything else returns error 255. The same applies to every checkpoint already on the target route.

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 to convert.

route_idinteger · min: 1Required

ID of the route to attach it to.

orderintegerRequired

Zero-based position at which to insert the checkpoint into the route.

Responses

200

Task converted

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/transmute

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

{
  "task_id": 1,
  "route_id": 1,
  "order": 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 route with such an ID, or tracker to which checkpoint assigned is unavailable to current sub-user).
255 - Invalid task state (if task or any of the checkpoints are not in unassigned or assigned state).

For the external_id_counts field in the response, see the task/route/create method description.

Required sub-user rights: task_update.

Update task

post

/task/update

Update a task. Pass a full task object including its id.

tracker_id is ignored, so this call cannot reassign a task. Use task/assign for that. The task owner cannot be changed either.

to is required and cannot be in the past, and from cannot be after to. Both rules are checked before anything else and report task.to or task.from rather than a top-level parameter. task.id must not be null.

Only a task in unassigned or assigned state can be changed. Anything else returns error 255.

Requires the task_update right.

Authorizations

AuthorizationstringRequired

Body

create_formbooleanOptional

Optional. Default false, for backward compatibility. When true, the form_template_id inside task is read and the task's form is created, replaced or deleted to match it.

Responses

200

Task updated

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/update

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

{
  "task": {
    "id": 1,
    "tracker_id": null,
    "location": {
      "lat": 1,
      "lng": 1,
      "address": "text",
      "radius": 1
    },
    "label": "text",
    "description": "text",
    "from": "2026-08-24 09:00:00",
    "to": "2026-08-24 09:00:00",
    "external_id": null,
    "status": "unassigned",
    "status_change_date": "text",
    "max_delay": 1,
    "min_stay_duration": 1,
    "min_arrival_duration": 1,
    "origin": "manual",
    "tags": [
      1
    ],
    "type": "task",
    "form": {
      "id": 1,
      "label": "text",
      "description": "text",
      "fields": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "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"
      }
    },
    "form_template_id": 1,
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "create_form": true
}

{
  "success": true,
  "external_id_counts": [
    {
      "external_id": "text",
      "count": 1
    }
  ]
}

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).
255 - Invalid task state (if current task state is not "unassigned" or "assigned").

Task

Task object

API actions

Assign task

Errors

Convert task batch

Count tasks

Create task

Errors

Delete task

Errors

List tasks

Read task

Errors

Convert task to checkpoint

Errors

Update task

Errors

More in this section

Checkpoints

Task history

Form

Task form files

Task form values

Route

Route optimization

Schedule

Task schedule checkpoints

Schedule proposals

Route schedules