> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/user-api/resources/field-service/task.md).

# 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](/docs/navixy-api/user-api/resources/field-service/form.md) 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](https://play.google.com/store/apps/details?id=com.navixy.xgps.tracker\&hl=ru) or [iOS](https://apps.apple.com/us/app/x-gps-tracker/id802887190), is visible to the person carrying it, who is also notified when a task is assigned or changed.

Tasks that repeat are [scheduled](/docs/navixy-api/user-api/resources/field-service/task/schedule.md) rather than created one by one, and tasks that must be done in sequence are grouped into a [route](/docs/navixy-api/user-api/resources/field-service/task/route.md). For a walkthrough, see [how to create and assign tasks](/docs/navixy-api/user-api/guides/field-service-management/manage-tasks.md).

## Task object

## The Task object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"Task":{"type":"object","description":"A task: a place to visit, a window to visit it in, and the conditions that decide whether it was done.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user, the office. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker this task is assigned to. **Ignored on update**, where reassignment goes through a separate operation.","minimum":1},"location":{"type":"object","description":"The circular geofence for this task. Entering and leaving it are what the platform watches. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location. Set this to associate the task with an address."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"label":{"type":"string","description":"Name of the task. 1 to 200 characters, and not blank.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description of the task. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"creation_date":{"type":"string","description":"When the task was created. **Read-only.**","readOnly":true},"from":{"type":"string","description":"Date after which the zone must be visited."},"to":{"type":"string","description":"Date before which the zone must be visited. Required, and cannot be in the past."},"external_id":{"type":["string","null"],"description":"Free text tying this record to an external system, such as an order number. 1 to 100 characters. For reference only.","minLength":1,"maxLength":100},"status":{"type":"string","description":"Current status. **Ignored on create and update.** `arrived` means the performer reached the geofence without completing the task, and `faulty` means it completed with problems.","enum":["unassigned","assigned","done","failed","delayed","arrived","faulty"]},"status_change_date":{"type":"string","description":"When the status last changed. **Ignored on create and update.**"},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000. Not listed in the published object description.","minimum":0,"maximum":512000},"arrival_date":{"type":["string","null"],"description":"When the tracker reached the zone, or null if it has not. **Read-only.**","readOnly":true},"stay_duration":{"type":"integer","description":"Seconds spent inside the zone. **Read-only.**","readOnly":true},"origin":{"type":"string","description":"How this record was created. **Ignored on create and update.** `imported` means it came from a spreadsheet.","enum":["manual","scheduled","imported"]},"tags":{"type":"array","description":"IDs of tags applied to this record.","items":{"type":"integer"}},"type":{"type":"string","description":"Which kind of record this is.","enum":["task","checkpoint","route"]},"form":{"allOf":[{"$ref":"#/components/schemas/Form"}],"description":"The attached form, when there is one."},"form_template_id":{"type":"integer","description":"ID of a form template. Read on create and update **only when `create_form` is `true`**."},"fields":{"type":"object","description":"Custom field values. Each key is a custom field ID **as a string**, and each value carries the field `type` and its `value`.","additionalProperties":true},"files":{"type":"array","description":"Files associated with this record. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"Form":{"type":"object","description":"A filled-in or fillable form. A form is created from a template and used once: after submission it is kept with its values for reference and cannot be reused.","properties":{"id":{"type":"integer","description":"Form ID."},"label":{"type":"string","description":"Form label, 1 to 100 characters.","minLength":1,"maxLength":100},"description":{"type":"string","description":"Form description. May be empty."},"fields":{"type":"array","description":"The form fields. See the form fields and values reference for the shape of each type.","items":{"type":"object","additionalProperties":true}},"created":{"type":"string","description":"When this form was created, or attached to its task. **Read-only.**","readOnly":true},"submit_in_zone":{"type":"boolean","description":"When `true`, the form can only be submitted inside the task zone."},"task_id":{"type":["integer","null"],"description":"ID of the task this form is attached to."},"checkin_id":{"type":["integer","null"],"description":"ID of the check-in this form belongs to, when it came from one."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker involved."},"template_id":{"type":["integer","null"],"description":"ID of the template this form was built from. **Null when that template has been deleted.**"},"template_version":{"type":["integer","null"],"description":"Version of the template at the time this form was created."},"values":{"type":["object","null"],"description":"The submitted values, keyed by field ID. **Null when the form has not been filled in.** See the form fields and values reference.","additionalProperties":true},"submitted":{"type":["string","null"],"description":"When the values were last submitted."},"submit_location":{"type":["object","null"],"description":"Where the values were last submitted.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."}}}}}}}}
```

Custom field values are keyed by custom field ID as a string. See [entity/fields](/docs/navixy-api/user-api/resources/commons/entity/fields.md). For the attached `form`, see the [form object](/docs/navixy-api/user-api/resources/field-service/form.md#form-object).

The `conditions` parameter of `task/list` takes [search conditions](/docs/navixy-api/user-api/resources/commons/entity/search_conditions.md).

## API actions

API base path: `/task`.

Operations that list no errors of their own return only the [general error codes](/docs/navixy-api/general/errors.md#error-codes).

***

*Required sub-user rights:* `task_update`.

## Assign task

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

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/assign":{"post":{"tags":["Tasks"],"summary":"Assign task","description":"Assign a task to a tracker, reassign it to a different one, or leave it unassigned.\n\nPass `tracker_id` as null, or leave it out, to unassign.\n\nOnly a task in `unassigned` or `assigned` state can be changed. Anything else returns error 255.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `task_update` right.","operationId":"taskAssign","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"integer","description":"ID of the task to assign.","minimum":1},"tracker_id":{"type":["integer","null"],"description":"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.","minimum":1}},"required":["task_id"]}}}},"responses":{"200":{"description":"Task assigned","$ref":"#/components/responses/OK"},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"402":{"description":"Error 236: the tracker's plan does not allow tasks.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 208: the tracker exists but is blocked, normally because its tariff ended.","$ref":"#/components/responses/ResponseError"},"404":{"description":"Error 204: no tracker with this ID belongs to the authorized user.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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

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

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"CheckedTask":{"type":"object","description":"A task parsed from a batch, with the same fields as a task plus any per-row problems found while checking it.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user, the office. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker this task is assigned to. **Ignored on update**, where reassignment goes through a separate operation.","minimum":1},"location":{"type":"object","description":"The circular geofence for this task. Entering and leaving it are what the platform watches. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location. Set this to associate the task with an address."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"label":{"type":"string","description":"Name of the task. 1 to 200 characters, and not blank.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description of the task. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"creation_date":{"type":"string","description":"When the task was created. **Read-only.**","readOnly":true},"from":{"type":"string","description":"Date after which the zone must be visited."},"to":{"type":"string","description":"Date before which the zone must be visited. Required, and cannot be in the past."},"external_id":{"type":["string","null"],"description":"Free text tying this record to an external system, such as an order number. 1 to 100 characters. For reference only.","minLength":1,"maxLength":100},"status":{"type":"string","description":"Current status. **Ignored on create and update.** `arrived` means the performer reached the geofence without completing the task, and `faulty` means it completed with problems.","enum":["unassigned","assigned","done","failed","delayed","arrived","faulty"]},"status_change_date":{"type":"string","description":"When the status last changed. **Ignored on create and update.**"},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000. Not listed in the published object description.","minimum":0,"maximum":512000},"arrival_date":{"type":["string","null"],"description":"When the tracker reached the zone, or null if it has not. **Read-only.**","readOnly":true},"stay_duration":{"type":"integer","description":"Seconds spent inside the zone. **Read-only.**","readOnly":true},"origin":{"type":"string","description":"How this record was created. **Ignored on create and update.** `imported` means it came from a spreadsheet.","enum":["manual","scheduled","imported"]},"tags":{"type":"array","description":"IDs of tags applied to this record.","items":{"type":"integer"}},"type":{"type":"string","description":"Which kind of record this is.","enum":["task","checkpoint","route"]},"form":{"allOf":[{"$ref":"#/components/schemas/Form"}],"description":"The attached form, when there is one."},"form_template_id":{"type":"integer","description":"ID of a form template. Read on create and update **only when `create_form` is `true`**."},"fields":{"type":"object","description":"Custom field values. Each key is a custom field ID **as a string**, and each value carries the field `type` and its `value`.","additionalProperties":true},"files":{"type":"array","description":"Files associated with this record. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true},"errors":{"type":"array","description":"Problems found in this row. Absent when the row is clean.","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"Form":{"type":"object","description":"A filled-in or fillable form. A form is created from a template and used once: after submission it is kept with its values for reference and cannot be reused.","properties":{"id":{"type":"integer","description":"Form ID."},"label":{"type":"string","description":"Form label, 1 to 100 characters.","minLength":1,"maxLength":100},"description":{"type":"string","description":"Form description. May be empty."},"fields":{"type":"array","description":"The form fields. See the form fields and values reference for the shape of each type.","items":{"type":"object","additionalProperties":true}},"created":{"type":"string","description":"When this form was created, or attached to its task. **Read-only.**","readOnly":true},"submit_in_zone":{"type":"boolean","description":"When `true`, the form can only be submitted inside the task zone."},"task_id":{"type":["integer","null"],"description":"ID of the task this form is attached to."},"checkin_id":{"type":["integer","null"],"description":"ID of the check-in this form belongs to, when it came from one."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker involved."},"template_id":{"type":["integer","null"],"description":"ID of the template this form was built from. **Null when that template has been deleted.**"},"template_version":{"type":["integer","null"],"description":"Version of the template at the time this form was created."},"values":{"type":["object","null"],"description":"The submitted values, keyed by field ID. **Null when the form has not been filled in.** See the form fields and values reference.","additionalProperties":true},"submitted":{"type":["string","null"],"description":"When the values were last submitted."},"submit_location":{"type":["object","null"],"description":"Where the values were last submitted.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."}}}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/batch_convert":{"post":{"tags":["Tasks"],"summary":"Convert task batch","description":"Parse a tab-delimited batch of tasks and return them checked, with per-row errors. **Creates nothing.**\n\nGive either `batch` or `file_id`. A request with neither returns error 7 with the message \"The 'batch' or 'file_id' parameter must be specified\".\n\nRecognised 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.\n\nWhen only `from` is given for a row, `to` is set to `from` plus `default_duration`.\n\nRequires the `task_update` right.","operationId":"taskBatchConvert","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"string","description":"Batch of tab-delimited tasks."},"file_id":{"type":"string","description":"Preloaded file ID, as an alternative to `batch`."},"fields":{"type":"array","description":"Optional. Column names, in order. Defaults to `[\"label\", \"from\", \"to\", \"address\", \"lat\", \"lng\", \"description\", \"min_stay_duration\", \"max_delay\", \"min_arrival_duration\"]`.","items":{"type":"string"}},"geocoder":{"type":"string","description":"Geocoder type to use for resolving addresses."},"default_radius":{"type":"integer","description":"Optional. Default 100. Zone radius in metres for a row that gives no `radius`."},"default_max_delay":{"type":"integer","description":"Optional. Default 0. Maximum delay in minutes for a row that gives no `max_delay`."},"default_duration":{"type":"integer","description":"Optional. Default 60. Task duration in minutes, used to derive `to` from `from`."},"default_min_stay_duration":{"type":"integer","description":"Optional. Default 0. Minimum stay in minutes for a row that gives no `min_stay_duration`."},"location_check_mode":{"type":"string","description":"Optional. Default `entity_location`. How to match a row to a place. With `entity_location`, `vehicle_ids` is ignored.","enum":["no_check","entity_location","parent_location"]},"employee_ids":{"type":"array","description":"Optional. Employees to distribute the tasks between automatically.","items":{"type":"integer"}},"vehicle_ids":{"type":"array","description":"Optional. Vehicles to distribute the tasks between automatically. **Ignored** when `location_check_mode` is `entity_location`.","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"The checked batch","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","description":"The parsed tasks, each with any problems found while checking it.","items":{"$ref":"#/components/schemas/CheckedTask"}},"limit_exceeded":{"type":"boolean","description":"`true` if the given batch was constrained by a limit."}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

***

## Count tasks

> Return the total number of tasks belonging to the current user.\
> \
> Callable with an empty body. Also accepts GET.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/count":{"post":{"tags":["Tasks"],"summary":"Count tasks","description":"Return the total number of tasks belonging to the current user.\n\nCallable with an empty body. Also accepts GET.","operationId":"taskCount","responses":{"200":{"description":"The count","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"count":{"type":"integer","description":"Number of tasks."}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

***

{% hint style="info" %}
`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.
{% endhint %}

For the `external_id_counts` field in the response, see the `task/route/create` [method description](/docs/navixy-api/user-api/resources/field-service/task/route.md#post-task-route-create).

*Required sub-user rights:* `task_update`.

## Create task

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

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Task":{"type":"object","description":"A task: a place to visit, a window to visit it in, and the conditions that decide whether it was done.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user, the office. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker this task is assigned to. **Ignored on update**, where reassignment goes through a separate operation.","minimum":1},"location":{"type":"object","description":"The circular geofence for this task. Entering and leaving it are what the platform watches. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location. Set this to associate the task with an address."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"label":{"type":"string","description":"Name of the task. 1 to 200 characters, and not blank.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description of the task. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"creation_date":{"type":"string","description":"When the task was created. **Read-only.**","readOnly":true},"from":{"type":"string","description":"Date after which the zone must be visited."},"to":{"type":"string","description":"Date before which the zone must be visited. Required, and cannot be in the past."},"external_id":{"type":["string","null"],"description":"Free text tying this record to an external system, such as an order number. 1 to 100 characters. For reference only.","minLength":1,"maxLength":100},"status":{"type":"string","description":"Current status. **Ignored on create and update.** `arrived` means the performer reached the geofence without completing the task, and `faulty` means it completed with problems.","enum":["unassigned","assigned","done","failed","delayed","arrived","faulty"]},"status_change_date":{"type":"string","description":"When the status last changed. **Ignored on create and update.**"},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000. Not listed in the published object description.","minimum":0,"maximum":512000},"arrival_date":{"type":["string","null"],"description":"When the tracker reached the zone, or null if it has not. **Read-only.**","readOnly":true},"stay_duration":{"type":"integer","description":"Seconds spent inside the zone. **Read-only.**","readOnly":true},"origin":{"type":"string","description":"How this record was created. **Ignored on create and update.** `imported` means it came from a spreadsheet.","enum":["manual","scheduled","imported"]},"tags":{"type":"array","description":"IDs of tags applied to this record.","items":{"type":"integer"}},"type":{"type":"string","description":"Which kind of record this is.","enum":["task","checkpoint","route"]},"form":{"allOf":[{"$ref":"#/components/schemas/Form"}],"description":"The attached form, when there is one."},"form_template_id":{"type":"integer","description":"ID of a form template. Read on create and update **only when `create_form` is `true`**."},"fields":{"type":"object","description":"Custom field values. Each key is a custom field ID **as a string**, and each value carries the field `type` and its `value`.","additionalProperties":true},"files":{"type":"array","description":"Files associated with this record. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"Form":{"type":"object","description":"A filled-in or fillable form. A form is created from a template and used once: after submission it is kept with its values for reference and cannot be reused.","properties":{"id":{"type":"integer","description":"Form ID."},"label":{"type":"string","description":"Form label, 1 to 100 characters.","minLength":1,"maxLength":100},"description":{"type":"string","description":"Form description. May be empty."},"fields":{"type":"array","description":"The form fields. See the form fields and values reference for the shape of each type.","items":{"type":"object","additionalProperties":true}},"created":{"type":"string","description":"When this form was created, or attached to its task. **Read-only.**","readOnly":true},"submit_in_zone":{"type":"boolean","description":"When `true`, the form can only be submitted inside the task zone."},"task_id":{"type":["integer","null"],"description":"ID of the task this form is attached to."},"checkin_id":{"type":["integer","null"],"description":"ID of the check-in this form belongs to, when it came from one."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker involved."},"template_id":{"type":["integer","null"],"description":"ID of the template this form was built from. **Null when that template has been deleted.**"},"template_version":{"type":["integer","null"],"description":"Version of the template at the time this form was created."},"values":{"type":["object","null"],"description":"The submitted values, keyed by field ID. **Null when the form has not been filled in.** See the form fields and values reference.","additionalProperties":true},"submitted":{"type":["string","null"],"description":"When the values were last submitted."},"submit_location":{"type":["object","null"],"description":"Where the values were last submitted.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."}}}}},"ExternalIdCounts":{"type":"array","description":"How many records share each `external_id` involved in this call, so a caller can spot a duplicate. Present only when the record carries an `external_id`.","items":{"type":"object","properties":{"external_id":{"type":"string","description":"The external ID."},"count":{"type":"integer","description":"How many records now carry it."}}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/create":{"post":{"tags":["Tasks"],"summary":"Create task","description":"Create a task, and return its ID.\n\n`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.\n\nSetting `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`.\n\nEach 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`.\n\nRequires the `task_update` right.","operationId":"taskCreate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task":{"allOf":[{"$ref":"#/components/schemas/Task"}],"description":"The task to create. Read-only fields are ignored, and `id` is always ignored here."},"create_form":{"type":"boolean","description":"Optional. Default `false`, for backward compatibility. When `true`, the `form_template_id` inside `task` is read and a form is created from that template."}},"required":["task"]}}}},"responses":{"200":{"description":"The created task","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"id":{"type":"integer","description":"ID of the new task."},"external_id_counts":{"$ref":"#/components/schemas/ExternalIdCounts"}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"402":{"description":"Error 236: the tracker's plan does not allow tasks.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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

> Delete a task by ID.\
> \
> Also accepts GET with the same parameters as query-string values.\
> \
> Requires the \`task\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/delete":{"post":{"tags":["Tasks"],"summary":"Delete task","description":"Delete a task by ID.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `task_update` right.","operationId":"taskDelete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"integer","description":"ID of the task to delete.","minimum":1}},"required":["task_id"]}}}},"responses":{"200":{"description":"Task deleted","$ref":"#/components/responses/OK"},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 201 - Not found in the database (if there is no task with such an ID).

***

## List tasks

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

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Task":{"type":"object","description":"A task: a place to visit, a window to visit it in, and the conditions that decide whether it was done.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user, the office. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker this task is assigned to. **Ignored on update**, where reassignment goes through a separate operation.","minimum":1},"location":{"type":"object","description":"The circular geofence for this task. Entering and leaving it are what the platform watches. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location. Set this to associate the task with an address."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"label":{"type":"string","description":"Name of the task. 1 to 200 characters, and not blank.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description of the task. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"creation_date":{"type":"string","description":"When the task was created. **Read-only.**","readOnly":true},"from":{"type":"string","description":"Date after which the zone must be visited."},"to":{"type":"string","description":"Date before which the zone must be visited. Required, and cannot be in the past."},"external_id":{"type":["string","null"],"description":"Free text tying this record to an external system, such as an order number. 1 to 100 characters. For reference only.","minLength":1,"maxLength":100},"status":{"type":"string","description":"Current status. **Ignored on create and update.** `arrived` means the performer reached the geofence without completing the task, and `faulty` means it completed with problems.","enum":["unassigned","assigned","done","failed","delayed","arrived","faulty"]},"status_change_date":{"type":"string","description":"When the status last changed. **Ignored on create and update.**"},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000. Not listed in the published object description.","minimum":0,"maximum":512000},"arrival_date":{"type":["string","null"],"description":"When the tracker reached the zone, or null if it has not. **Read-only.**","readOnly":true},"stay_duration":{"type":"integer","description":"Seconds spent inside the zone. **Read-only.**","readOnly":true},"origin":{"type":"string","description":"How this record was created. **Ignored on create and update.** `imported` means it came from a spreadsheet.","enum":["manual","scheduled","imported"]},"tags":{"type":"array","description":"IDs of tags applied to this record.","items":{"type":"integer"}},"type":{"type":"string","description":"Which kind of record this is.","enum":["task","checkpoint","route"]},"form":{"allOf":[{"$ref":"#/components/schemas/Form"}],"description":"The attached form, when there is one."},"form_template_id":{"type":"integer","description":"ID of a form template. Read on create and update **only when `create_form` is `true`**."},"fields":{"type":"object","description":"Custom field values. Each key is a custom field ID **as a string**, and each value carries the field `type` and its `value`.","additionalProperties":true},"files":{"type":"array","description":"Files associated with this record. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"Form":{"type":"object","description":"A filled-in or fillable form. A form is created from a template and used once: after submission it is kept with its values for reference and cannot be reused.","properties":{"id":{"type":"integer","description":"Form ID."},"label":{"type":"string","description":"Form label, 1 to 100 characters.","minLength":1,"maxLength":100},"description":{"type":"string","description":"Form description. May be empty."},"fields":{"type":"array","description":"The form fields. See the form fields and values reference for the shape of each type.","items":{"type":"object","additionalProperties":true}},"created":{"type":"string","description":"When this form was created, or attached to its task. **Read-only.**","readOnly":true},"submit_in_zone":{"type":"boolean","description":"When `true`, the form can only be submitted inside the task zone."},"task_id":{"type":["integer","null"],"description":"ID of the task this form is attached to."},"checkin_id":{"type":["integer","null"],"description":"ID of the check-in this form belongs to, when it came from one."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker involved."},"template_id":{"type":["integer","null"],"description":"ID of the template this form was built from. **Null when that template has been deleted.**"},"template_version":{"type":["integer","null"],"description":"Version of the template at the time this form was created."},"values":{"type":["object","null"],"description":"The submitted values, keyed by field ID. **Null when the form has not been filled in.** See the form fields and values reference.","additionalProperties":true},"submitted":{"type":["string","null"],"description":"When the values were last submitted."},"submit_location":{"type":["object","null"],"description":"Where the values were last submitted.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."}}}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/list":{"post":{"tags":["Tasks"],"summary":"List tasks","description":"List the tasks of the current user, with filtering, sorting and pagination.\n\nA parameter left out or set to null is simply not used as a filter.\n\nCallable with an empty body. Also accepts GET with the same parameters as query-string values.","operationId":"taskList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string","description":"Optional. External task ID to search for. Up to 100 characters.","maxLength":100},"statuses":{"type":"array","description":"Optional. Default all. Restrict to these task statuses.","items":{"type":"string","enum":["unassigned","assigned","done","failed","delayed","arrived","faulty"]},"minItems":1},"trackers":{"type":"array","description":"Optional. IDs of the trackers the tasks are assigned to. Must not contain duplicates.","items":{"type":"integer"}},"from":{"type":"string","description":"Optional. Include tasks that are actual after this date."},"to":{"type":"string","description":"Optional. Include tasks that are actual before this date."},"conditions":{"type":"array","description":"Optional. Search conditions to apply. **At most 60.** Conditions may be built on `id`, `employee` (an ID), `status`, `label`, `location` (the address), `from`, `to`, `status_change_date`, `arrival_date`, `stay_duration` (seconds), `description`, `external_id`, and `form` (the template ID).","items":{"type":"object","additionalProperties":true},"maxItems":60},"filter":{"type":"string","description":"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.","maxLength":100},"filters":{"type":"array","description":"Optional. Filters for task label, description or address.","items":{"type":"string"}},"tag_ids":{"type":"array","description":"Optional. Restrict to tasks carrying these tag IDs.","items":{"type":"integer"}},"location":{"type":"object","description":"Optional. Return only tasks whose zone centre lies inside this circle.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"radius":{"type":"integer","description":"Radius in metres."}}},"sort":{"type":"array","description":"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).","items":{"type":"string"}},"offset":{"type":"integer","description":"Optional. Default 0. Offset into the found tasks, for pagination.","minimum":0},"limit":{"type":"integer","description":"Optional. Default 10000, maximum 100000. Number of tasks to return.","minimum":0,"maximum":100000}}}}}},"responses":{"200":{"description":"Matching tasks","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"count":{"type":"integer","description":"Total number of tasks found, ignoring pagination."}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

***

## Read task

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

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Task":{"type":"object","description":"A task: a place to visit, a window to visit it in, and the conditions that decide whether it was done.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user, the office. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker this task is assigned to. **Ignored on update**, where reassignment goes through a separate operation.","minimum":1},"location":{"type":"object","description":"The circular geofence for this task. Entering and leaving it are what the platform watches. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location. Set this to associate the task with an address."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"label":{"type":"string","description":"Name of the task. 1 to 200 characters, and not blank.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description of the task. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"creation_date":{"type":"string","description":"When the task was created. **Read-only.**","readOnly":true},"from":{"type":"string","description":"Date after which the zone must be visited."},"to":{"type":"string","description":"Date before which the zone must be visited. Required, and cannot be in the past."},"external_id":{"type":["string","null"],"description":"Free text tying this record to an external system, such as an order number. 1 to 100 characters. For reference only.","minLength":1,"maxLength":100},"status":{"type":"string","description":"Current status. **Ignored on create and update.** `arrived` means the performer reached the geofence without completing the task, and `faulty` means it completed with problems.","enum":["unassigned","assigned","done","failed","delayed","arrived","faulty"]},"status_change_date":{"type":"string","description":"When the status last changed. **Ignored on create and update.**"},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000. Not listed in the published object description.","minimum":0,"maximum":512000},"arrival_date":{"type":["string","null"],"description":"When the tracker reached the zone, or null if it has not. **Read-only.**","readOnly":true},"stay_duration":{"type":"integer","description":"Seconds spent inside the zone. **Read-only.**","readOnly":true},"origin":{"type":"string","description":"How this record was created. **Ignored on create and update.** `imported` means it came from a spreadsheet.","enum":["manual","scheduled","imported"]},"tags":{"type":"array","description":"IDs of tags applied to this record.","items":{"type":"integer"}},"type":{"type":"string","description":"Which kind of record this is.","enum":["task","checkpoint","route"]},"form":{"allOf":[{"$ref":"#/components/schemas/Form"}],"description":"The attached form, when there is one."},"form_template_id":{"type":"integer","description":"ID of a form template. Read on create and update **only when `create_form` is `true`**."},"fields":{"type":"object","description":"Custom field values. Each key is a custom field ID **as a string**, and each value carries the field `type` and its `value`.","additionalProperties":true},"files":{"type":"array","description":"Files associated with this record. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"Form":{"type":"object","description":"A filled-in or fillable form. A form is created from a template and used once: after submission it is kept with its values for reference and cannot be reused.","properties":{"id":{"type":"integer","description":"Form ID."},"label":{"type":"string","description":"Form label, 1 to 100 characters.","minLength":1,"maxLength":100},"description":{"type":"string","description":"Form description. May be empty."},"fields":{"type":"array","description":"The form fields. See the form fields and values reference for the shape of each type.","items":{"type":"object","additionalProperties":true}},"created":{"type":"string","description":"When this form was created, or attached to its task. **Read-only.**","readOnly":true},"submit_in_zone":{"type":"boolean","description":"When `true`, the form can only be submitted inside the task zone."},"task_id":{"type":["integer","null"],"description":"ID of the task this form is attached to."},"checkin_id":{"type":["integer","null"],"description":"ID of the check-in this form belongs to, when it came from one."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker involved."},"template_id":{"type":["integer","null"],"description":"ID of the template this form was built from. **Null when that template has been deleted.**"},"template_version":{"type":["integer","null"],"description":"Version of the template at the time this form was created."},"values":{"type":["object","null"],"description":"The submitted values, keyed by field ID. **Null when the form has not been filled in.** See the form fields and values reference.","additionalProperties":true},"submitted":{"type":["string","null"],"description":"When the values were last submitted."},"submit_location":{"type":["object","null"],"description":"Where the values were last submitted.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."}}}}},"TaskCheckpoint":{"type":"object","description":"A checkpoint: one stop on a route. It carries every field a task does, plus its position in the route.\n\nA checkpoint inherits its performer from its route, so `tracker_id` is ignored on update.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user, the office. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker this checkpoint is assigned to. **Ignored on update**, where reassignment goes through a separate operation.","minimum":1},"location":{"type":"object","description":"The circular geofence for this checkpoint. Entering and leaving it are what the platform watches. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location. Set this to associate the task with an address."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"label":{"type":"string","description":"Name of the checkpoint. 1 to 200 characters, and not blank.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description of the checkpoint. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"creation_date":{"type":"string","description":"When the checkpoint was created. **Read-only.**","readOnly":true},"from":{"type":"string","description":"Date after which the zone must be visited."},"to":{"type":"string","description":"Date before which the zone must be visited. Required, and cannot be in the past."},"external_id":{"type":["string","null"],"description":"Free text tying this record to an external system, such as an order number. 1 to 100 characters. For reference only.","minLength":1,"maxLength":100},"status":{"type":"string","description":"Current status. **Ignored on create and update.** `arrived` means the performer reached the geofence without completing the checkpoint, and `faulty` means it completed with problems.","enum":["unassigned","assigned","done","failed","delayed","arrived","faulty"]},"status_change_date":{"type":"string","description":"When the status last changed. **Ignored on create and update.**"},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000. Not listed in the published object description.","minimum":0,"maximum":512000},"arrival_date":{"type":["string","null"],"description":"When the tracker reached the zone, or null if it has not. **Read-only.**","readOnly":true},"stay_duration":{"type":"integer","description":"Seconds spent inside the zone. **Read-only.**","readOnly":true},"origin":{"type":"string","description":"How this record was created. **Ignored on create and update.** `imported` means it came from a spreadsheet.","enum":["manual","scheduled","imported"]},"tags":{"type":"array","description":"IDs of tags applied to this record.","items":{"type":"integer"}},"type":{"type":"string","description":"Which kind of record this is.","enum":["task","checkpoint","route"]},"form":{"allOf":[{"$ref":"#/components/schemas/Form"}],"description":"The attached form, when there is one."},"form_template_id":{"type":"integer","description":"ID of a form template. Read on create and update **only when `create_form` is `true`**."},"fields":{"type":"object","description":"Custom field values. Each key is a custom field ID **as a string**, and each value carries the field `type` and its `value`.","additionalProperties":true},"files":{"type":"array","description":"Files associated with this record. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true},"parent_id":{"type":"integer","description":"ID of the route this checkpoint belongs to.","minimum":1},"order":{"type":"integer","description":"Zero-based position of this checkpoint within its route.","minimum":0}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/read":{"post":{"tags":["Tasks"],"summary":"Read task","description":"Return a task, a checkpoint, or a route with its checkpoints, by ID.\n\nWhich of the three you get depends on what the ID belongs to. `checkpoints` is present only when the ID is a route.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"taskRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"integer","description":"ID of the task, route or checkpoint.","minimum":1}},"required":["task_id"]}}}},"responses":{"200":{"description":"The task, checkpoint or route","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"value":{"$ref":"#/components/schemas/Task"},"checkpoints":{"type":"array","description":"Every checkpoint of the route. Present only when the given ID is a route.","items":{"$ref":"#/components/schemas/TaskCheckpoint"}}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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

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

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/transmute":{"post":{"tags":["Tasks"],"summary":"Convert task to checkpoint","description":"Convert a task into a checkpoint of an existing route.\n\nThe checkpoint is inserted at `order`, and any checkpoint already at that position, along with everything after it, shifts one place right.\n\nOnly 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.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `task_update` right.","operationId":"taskTransmute","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"integer","description":"ID of the task to convert.","minimum":1},"route_id":{"type":"integer","description":"ID of the route to attach it to.","minimum":1},"order":{"type":"integer","description":"Zero-based position at which to insert the checkpoint into the route.","minimum":0}},"required":["task_id","route_id","order"]}}}},"responses":{"200":{"description":"Task converted","$ref":"#/components/responses/OK"},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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](/docs/navixy-api/user-api/resources/field-service/task/route.md#post-task-route-create).

*Required sub-user rights:* `task_update`.

## Update task

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

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"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.","name":"Authorization","in":"header"}},"schemas":{"Task":{"type":"object","description":"A task: a place to visit, a window to visit it in, and the conditions that decide whether it was done.","properties":{"id":{"type":"integer","description":"Primary key. Used when updating; **ignored when creating**."},"user_id":{"type":"integer","description":"ID of the owning user, the office. **Read-only.**","readOnly":true},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker this task is assigned to. **Ignored on update**, where reassignment goes through a separate operation.","minimum":1},"location":{"type":"object","description":"The circular geofence for this task. Entering and leaving it are what the platform watches. Cannot be null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address of the location. Set this to associate the task with an address."},"radius":{"type":"integer","description":"Radius of the zone in metres, from 1 to 300000.","minimum":1,"maximum":300000}}},"label":{"type":"string","description":"Name of the task. 1 to 200 characters, and not blank.","minLength":1,"maxLength":200},"description":{"type":"string","description":"Description of the task. Up to 1024 characters. **Required**, but may be an empty string.","maxLength":1024},"creation_date":{"type":"string","description":"When the task was created. **Read-only.**","readOnly":true},"from":{"type":"string","description":"Date after which the zone must be visited."},"to":{"type":"string","description":"Date before which the zone must be visited. Required, and cannot be in the past."},"external_id":{"type":["string","null"],"description":"Free text tying this record to an external system, such as an order number. 1 to 100 characters. For reference only.","minLength":1,"maxLength":100},"status":{"type":"string","description":"Current status. **Ignored on create and update.** `arrived` means the performer reached the geofence without completing the task, and `faulty` means it completed with problems.","enum":["unassigned","assigned","done","failed","delayed","arrived","faulty"]},"status_change_date":{"type":"string","description":"When the status last changed. **Ignored on create and update.**"},"max_delay":{"type":"integer","description":"Maximum allowed completion delay, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_stay_duration":{"type":"integer","description":"Minimum time that must be spent inside the zone for completion, in minutes. Default 0, up to 512000.","minimum":0,"maximum":512000},"min_arrival_duration":{"type":"integer","description":"Visits shorter than this do not count as an arrival, in minutes. Default 0, up to 512000. Not listed in the published object description.","minimum":0,"maximum":512000},"arrival_date":{"type":["string","null"],"description":"When the tracker reached the zone, or null if it has not. **Read-only.**","readOnly":true},"stay_duration":{"type":"integer","description":"Seconds spent inside the zone. **Read-only.**","readOnly":true},"origin":{"type":"string","description":"How this record was created. **Ignored on create and update.** `imported` means it came from a spreadsheet.","enum":["manual","scheduled","imported"]},"tags":{"type":"array","description":"IDs of tags applied to this record.","items":{"type":"integer"}},"type":{"type":"string","description":"Which kind of record this is.","enum":["task","checkpoint","route"]},"form":{"allOf":[{"$ref":"#/components/schemas/Form"}],"description":"The attached form, when there is one."},"form_template_id":{"type":"integer","description":"ID of a form template. Read on create and update **only when `create_form` is `true`**."},"fields":{"type":"object","description":"Custom field values. Each key is a custom field ID **as a string**, and each value carries the field `type` and its `value`.","additionalProperties":true},"files":{"type":"array","description":"Files associated with this record. **Read-only**, and not listed in the published object description.","items":{"type":"object","additionalProperties":true},"readOnly":true}}},"Form":{"type":"object","description":"A filled-in or fillable form. A form is created from a template and used once: after submission it is kept with its values for reference and cannot be reused.","properties":{"id":{"type":"integer","description":"Form ID."},"label":{"type":"string","description":"Form label, 1 to 100 characters.","minLength":1,"maxLength":100},"description":{"type":"string","description":"Form description. May be empty."},"fields":{"type":"array","description":"The form fields. See the form fields and values reference for the shape of each type.","items":{"type":"object","additionalProperties":true}},"created":{"type":"string","description":"When this form was created, or attached to its task. **Read-only.**","readOnly":true},"submit_in_zone":{"type":"boolean","description":"When `true`, the form can only be submitted inside the task zone."},"task_id":{"type":["integer","null"],"description":"ID of the task this form is attached to."},"checkin_id":{"type":["integer","null"],"description":"ID of the check-in this form belongs to, when it came from one."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker involved."},"template_id":{"type":["integer","null"],"description":"ID of the template this form was built from. **Null when that template has been deleted.**"},"template_version":{"type":["integer","null"],"description":"Version of the template at the time this form was created."},"values":{"type":["object","null"],"description":"The submitted values, keyed by field ID. **Null when the form has not been filled in.** See the form fields and values reference.","additionalProperties":true},"submitted":{"type":["string","null"],"description":"When the values were last submitted."},"submit_location":{"type":["object","null"],"description":"Where the values were last submitted.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."}}}}},"ExternalIdCounts":{"type":"array","description":"How many records share each `external_id` involved in this call, so a caller can spot a duplicate. Present only when the record carries an `external_id`.","items":{"type":"object","properties":{"external_id":{"type":"string","description":"The external ID."},"count":{"type":"integer","description":"How many records now carry it."}}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/update":{"post":{"tags":["Tasks"],"summary":"Update task","description":"Update a task. Pass a full task object including its `id`.\n\n**`tracker_id` is ignored**, so this call cannot reassign a task. Use `task/assign` for that. The task owner cannot be changed either.\n\n`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.\n\nOnly a task in `unassigned` or `assigned` state can be changed. Anything else returns error 255.\n\nRequires the `task_update` right.","operationId":"taskUpdate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task":{"allOf":[{"$ref":"#/components/schemas/Task"}],"description":"The task to update, including its `id`. Read-only fields and `tracker_id` are ignored."},"create_form":{"type":"boolean","description":"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."}},"required":["task"]}}}},"responses":{"200":{"description":"Task updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"external_id_counts":{"$ref":"#/components/schemas/ExternalIdCounts"}}}}}},"400":{"description":"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.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#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

#### Checkpoints

| Endpoint                                                                                                                            | Method | What it does               |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------ | -------------------------- |
| [`/task/checkpoint/create`](/docs/navixy-api/user-api/resources/field-service/task/checkpoint.md#post-task-checkpoint-create)       | POST   | Create checkpoint          |
| [`/task/checkpoint/delete`](/docs/navixy-api/user-api/resources/field-service/task/checkpoint.md#post-task-checkpoint-delete)       | POST   | Delete checkpoint          |
| [`/task/checkpoint/list`](/docs/navixy-api/user-api/resources/field-service/task/checkpoint.md#post-task-checkpoint-list)           | POST   | List checkpoints           |
| [`/task/checkpoint/read`](/docs/navixy-api/user-api/resources/field-service/task/checkpoint.md#post-task-checkpoint-read)           | POST   | Read checkpoint            |
| [`/task/checkpoint/transmute`](/docs/navixy-api/user-api/resources/field-service/task/checkpoint.md#post-task-checkpoint-transmute) | POST   | Convert checkpoint to task |
| [`/task/checkpoint/update`](/docs/navixy-api/user-api/resources/field-service/task/checkpoint.md#post-task-checkpoint-update)       | POST   | Update checkpoint          |

#### Task history

| Endpoint                                                                                                         | Method | What it does      |
| ---------------------------------------------------------------------------------------------------------------- | ------ | ----------------- |
| [`/task/history/list`](/docs/navixy-api/user-api/resources/field-service/task/history.md#post-task-history-list) | POST   | List task history |

#### Form

| Endpoint                                                                                                        | Method | What it does        |
| --------------------------------------------------------------------------------------------------------------- | ------ | ------------------- |
| [`/task/form/create`](/docs/navixy-api/user-api/resources/field-service/task/form.md#post-task-form-create)     | POST   | Attach form to task |
| [`/task/form/delete`](/docs/navixy-api/user-api/resources/field-service/task/form.md#post-task-form-delete)     | POST   | Delete task form    |
| [`/task/form/download`](/docs/navixy-api/user-api/resources/field-service/task/form.md#post-task-form-download) | POST   | Download task form  |
| [`/task/form/list`](/docs/navixy-api/user-api/resources/field-service/task/form.md#post-task-form-list)         | POST   | List forms          |
| [`/task/form/read`](/docs/navixy-api/user-api/resources/field-service/task/form.md#post-task-form-read)         | POST   | Read task form      |

#### Task form files

| Endpoint                                                                                                                   | Method | What it does     |
| -------------------------------------------------------------------------------------------------------------------------- | ------ | ---------------- |
| [`/task/form/file/create`](/docs/navixy-api/user-api/resources/field-service/task/form/file.md#post-task-form-file-create) | POST   | Create form file |

#### Task form values

| Endpoint                                                                                                                         | Method | What it does       |
| -------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------ |
| [`/task/form/values/update`](/docs/navixy-api/user-api/resources/field-service/task/form/values.md#post-task-form-values-update) | POST   | Update form values |

#### Route

| Endpoint                                                                                                       | Method | What it does |
| -------------------------------------------------------------------------------------------------------------- | ------ | ------------ |
| [`/task/route/assign`](/docs/navixy-api/user-api/resources/field-service/task/route.md#post-task-route-assign) | POST   | Assign route |
| [`/task/route/create`](/docs/navixy-api/user-api/resources/field-service/task/route.md#post-task-route-create) | POST   | Create route |
| [`/task/route/delete`](/docs/navixy-api/user-api/resources/field-service/task/route.md#post-task-route-delete) | POST   | Delete route |
| [`/task/route/list`](/docs/navixy-api/user-api/resources/field-service/task/route.md#post-task-route-list)     | POST   | List routes  |
| [`/task/route/read`](/docs/navixy-api/user-api/resources/field-service/task/route.md#post-task-route-read)     | POST   | Read route   |
| [`/task/route/update`](/docs/navixy-api/user-api/resources/field-service/task/route.md#post-task-route-update) | POST   | Update route |

#### Route optimization

| Endpoint                                                                                                                                  | Method | What it does          |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------- |
| [`/task/route/points/optimize`](/docs/navixy-api/user-api/resources/field-service/task/route/optimize.md#post-task-route-points-optimize) | POST   | Optimize route points |

#### Schedule

| Endpoint                                                                                                                | Method | What it does         |
| ----------------------------------------------------------------------------------------------------------------------- | ------ | -------------------- |
| [`/task/schedule/create`](/docs/navixy-api/user-api/resources/field-service/task/schedule.md#post-task-schedule-create) | POST   | Create task schedule |
| [`/task/schedule/delete`](/docs/navixy-api/user-api/resources/field-service/task/schedule.md#post-task-schedule-delete) | POST   | Delete task schedule |
| [`/task/schedule/list`](/docs/navixy-api/user-api/resources/field-service/task/schedule.md#post-task-schedule-list)     | POST   | List task schedules  |
| [`/task/schedule/read`](/docs/navixy-api/user-api/resources/field-service/task/schedule.md#post-task-schedule-read)     | POST   | Read task schedule   |
| [`/task/schedule/update`](/docs/navixy-api/user-api/resources/field-service/task/schedule.md#post-task-schedule-update) | POST   | Update task schedule |

#### Task schedule checkpoints

| Endpoint                                                                                                                                                       | Method | What it does                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------- |
| [`/task/schedule/checkpoint/delete`](/docs/navixy-api/user-api/resources/field-service/task/schedule/checkpoint.md#post-task-schedule-checkpoint-delete)       | POST   | Delete schedule checkpoint          |
| [`/task/schedule/checkpoint/transmute`](/docs/navixy-api/user-api/resources/field-service/task/schedule/checkpoint.md#post-task-schedule-checkpoint-transmute) | POST   | Convert schedule checkpoint to task |

#### Schedule proposals

| Endpoint                                                                                                                                       | Method | What it does            |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------- |
| [`/task/schedule/proposal/list`](/docs/navixy-api/user-api/resources/field-service/task/schedule/proposal.md#post-task-schedule-proposal-list) | POST   | List schedule proposals |

#### Route schedules

| Endpoint                                                                                                                                  | Method | What it does          |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------- |
| [`/task/schedule/route/create`](/docs/navixy-api/user-api/resources/field-service/task/schedule/route.md#post-task-schedule-route-create) | POST   | Create route schedule |
| [`/task/schedule/route/delete`](/docs/navixy-api/user-api/resources/field-service/task/schedule/route.md#post-task-schedule-route-delete) | POST   | Delete route schedule |
| [`/task/schedule/route/update`](/docs/navixy-api/user-api/resources/field-service/task/schedule/route.md#post-task-schedule-route-update) | POST   | Update route schedule |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://navixy.com/docs/navixy-api/user-api/resources/field-service/task.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.