Route
A named, ordered set of checkpoints that must be visited in sequence.
A route is a named, ordered set of checkpoints, each of which is essentially a task with a link back to the route.
Order is what separates a route from a set of separate tasks. A route completes only when every checkpoint has completed and they were visited in the specified sequence. Otherwise it completes with warnings, or fails.
Route object
API actions
API base path: /task/route.
Operations that list no errors of their own return only the general error codes.
Required sub-user rights: task_update.
Assign a route 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 route 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.
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.
ID of the route to assign.
ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked. Null leaves the route assigned to no one.
Route assigned
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 236: the tracker's plan does not allow tasks.
Error 208: the tracker exists but is blocked, normally because its tariff ended.
Error 204: no tracker with this ID belongs to the authorized user.
Error response object
POST /v2/task/route/assign HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 32
{
"route_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.
Give the checkpoints in order of execution. Their from and to must be agreed with each other, so a checkpoint's to cannot be before the from of a preceding one.
One of the checkpoints can have an ID, in which case it must be a task, and it will be transmuted from task to checkpoint.
Required sub-user rights: task_update.
Create a route together with its checkpoints, and return the created route.
A route needs between 2 and 500 checkpoints. Sending one returns error 7 with "size must be between 2 and 500".
Give the checkpoints in order of execution. Their windows must agree with each other: a checkpoint's to cannot be before the from of a preceding one. The route's own from and to are computed from the first and last checkpoint, which is why both are ignored on the route object.
One checkpoint may carry an id, in which case it must be an existing task, and it is converted into a checkpoint of this route.
external_id_counts reports each external ID that now has a count above zero. Different checkpoints may carry different external IDs, so several can come back. When there is nothing to report the field is absent.
Requires the task_update right.
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.
Optional. Default false, for backward compatibility. When true, the form_template_id inside each checkpoint is read and a form is created from that template.
The created route
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 236: the tracker's plan does not allow tasks.
Error response object
POST /v2/task/route/create HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1041
{
"route": {
"id": 1,
"tracker_id": null,
"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",
"origin": "manual",
"tags": [
1
],
"checkpoint_ids": [
1
],
"type": "route"
},
"checkpoints": [
{
"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"
},
"parent_id": 1,
"order": 1
}
],
"create_form": true
}{
"success": true,
"result": {
"id": 1,
"user_id": 1,
"tracker_id": null,
"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",
"origin": "manual",
"tags": [
1
],
"checkpoint_ids": [
1
],
"type": "route"
},
"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 a route and all of its checkpoints by ID.
Also accepts GET with the same parameters as query-string values.
Requires the task_update right.
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.
ID of the route to delete.
Route deleted
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/task/route/delete HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 14
{
"route_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 route with such an ID.
List the routes of the current user, with optional filtering.
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.
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.
Optional. IDs of the trackers the routes are assigned to.
Optional. Include routes that are actual after this date.
2026-08-24 09:00:00Optional. Include routes that are actual before this date.
2026-08-24 09:00:00Optional. Filter over route label and description, up to 100 characters.
Matching routes
true if request finished successfully.
trueTotal number of routes found.
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.
Error response object
POST /v2/task/route/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 114
{
"statuses": [
"unassigned"
],
"trackers": [
1
],
"from": "2026-08-24 09:00:00",
"to": "2026-08-24 09:00:00",
"filter": "text"
}{
"success": true,
"list": [
{
"id": 1,
"user_id": 1,
"tracker_id": null,
"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",
"origin": "manual",
"tags": [
1
],
"checkpoint_ids": [
1
],
"type": "route"
}
],
"count": 1
}Return one route by ID.
Also accepts GET with the same parameters as query-string values.
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.
ID of the route.
The route
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/task/route/read HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 14
{
"route_id": 1
}{
"success": true,
"value": {
"id": 1,
"user_id": 1,
"tracker_id": null,
"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",
"origin": "manual",
"tags": [
1
],
"checkpoint_ids": [
1
],
"type": "route"
}
}Errors
These errors come in addition to the general error codes:
201 - Not found in the database - if there is no route with such an ID.
Note that you cannot change task owner using this method. Reordering checkpoint IDs in the checkpoint_ids array changes order of execution.
Required sub-user rights: task_update.
Update a route and its checkpoints, and return the updated route.
Reordering the IDs in checkpoint_ids changes the order of execution. The route owner cannot be changed.
Checkpoints not included in the request are deleted. A checkpoint carrying an id is updated, one without an id is created. checkpoints should be null when the route's checkpoint_ids is null, and not null otherwise.
Only a route in unassigned or assigned state can be changed. Anything else returns error 255.
Requires the task_update right.
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.
Optional. Default false, for backward compatibility. When true, the form_template_id inside each checkpoint is read and that checkpoint's form is created, replaced or deleted to match it.
The updated route
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/task/route/update HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1041
{
"route": {
"id": 1,
"tracker_id": null,
"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",
"origin": "manual",
"tags": [
1
],
"checkpoint_ids": [
1
],
"type": "route"
},
"checkpoints": [
{
"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"
},
"parent_id": 1,
"order": 1
}
],
"create_form": true
}{
"success": true,
"result": {
"id": 1,
"user_id": 1,
"tracker_id": null,
"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",
"origin": "manual",
"tags": [
1
],
"checkpoint_ids": [
1
],
"type": "route"
}
}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".
More in this section
Route optimization
Last updated
Was this helpful?