> 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/checkpoint.md).

# Checkpoints

The individual stops that make up a route, each essentially a task.

A checkpoint is one stop on a [route](/docs/navixy-api/user-api/resources/field-service/task/route.md). It is essentially a [task](/docs/navixy-api/user-api/resources/field-service/task.md) with an extra link to the parent route, so it carries the same fields and completes the same way.

These operations work on checkpoints individually, which is what changing one stop on an existing route needs. Creating a route creates its checkpoints with it.

## Checkpoint object

## The TaskCheckpoint object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"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}}},"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."}}}}}}}}
```

For the attached `form`, see the [form object](/docs/navixy-api/user-api/resources/field-service/form.md#form-object).

## API actions

API base path: `/task/checkpoint`.

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

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 checkpoint

> Create a checkpoint on an existing route, and return its ID.\
> \
> The checkpoint is inserted at \`order\` in the parent route's checkpoint list, and any checkpoint already at that position, along with everything after it, shifts one place right.\
> \
> \`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.\
> \
> 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":{"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}}},"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/checkpoint/create":{"post":{"tags":["Tasks"],"summary":"Create checkpoint","description":"Create a checkpoint on an existing route, and return its ID.\n\nThe checkpoint is inserted at `order` in the parent route's checkpoint list, and any checkpoint already at that position, along with everything after it, shifts one place right.\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\nRequires the `task_update` right.","operationId":"taskCheckpointCreate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint":{"allOf":[{"$ref":"#/components/schemas/TaskCheckpoint"}],"description":"The checkpoint to create, without `id`. Read-only fields are ignored."},"create_form":{"type":"boolean","description":"Optional. Default `false`. When `true`, the `form_template_id` inside `checkpoint` is read and a form is created from that template."}},"required":["checkpoint"]}}}},"responses":{"200":{"description":"The created checkpoint","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 checkpoint."},"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 checkpoint

> Delete a checkpoint by ID. The remaining checkpoints on the route close the gap.\
> \
> 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/checkpoint/delete":{"post":{"tags":["Tasks"],"summary":"Delete checkpoint","description":"Delete a checkpoint by ID. The remaining checkpoints on the route close the gap.\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":"taskCheckpointDelete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint_id":{"type":"integer","description":"ID of the checkpoint to delete.","minimum":1}},"required":["checkpoint_id"]}}}},"responses":{"200":{"description":"Checkpoint 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 checkpoint with such an ID.

***

## List checkpoints

> Return checkpoints by ID.\
> \
> \*\*\`checkpoint\_ids\` is required and must not be empty\*\*, so this operation reads a known set rather than browsing all checkpoints.\
> \
> 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":{"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}}},"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/checkpoint/list":{"post":{"tags":["Tasks"],"summary":"List checkpoints","description":"Return checkpoints by ID.\n\n**`checkpoint_ids` is required and must not be empty**, so this operation reads a known set rather than browsing all checkpoints.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"taskCheckpointList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint_ids":{"type":"array","description":"IDs of the checkpoints to return. Must not be empty.","items":{"type":"integer"},"minItems":1}},"required":["checkpoint_ids"]}}}},"responses":{"200":{"description":"Matching checkpoints","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/TaskCheckpoint"}},"count":{"type":"integer","description":"Total number of checkpoints found."}}}}}},"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 checkpoint

> Return one checkpoint by ID.\
> \
> 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":{"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}}},"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/checkpoint/read":{"post":{"tags":["Tasks"],"summary":"Read checkpoint","description":"Return one checkpoint by ID.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"taskCheckpointRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint_id":{"type":"integer","description":"ID of the checkpoint.","minimum":1}},"required":["checkpoint_id"]}}}},"responses":{"200":{"description":"The checkpoint","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"value":{"$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 checkpoint with such an ID.

***

If the converted checkpoint was the only one in its route, the route is deleted.

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

## Convert checkpoint to task

> Convert a checkpoint back into a standalone task, detaching it from its route.\
> \
> Only a task in \`unassigned\` or \`assigned\` state can be changed. Anything else returns error 255. Every checkpoint on the route is checked, not just this one.\
> \
> 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/checkpoint/transmute":{"post":{"tags":["Tasks"],"summary":"Convert checkpoint to task","description":"Convert a checkpoint back into a standalone task, detaching it from its route.\n\nOnly a task in `unassigned` or `assigned` state can be changed. Anything else returns error 255. Every checkpoint on the route is checked, not just this one.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `task_update` right.","operationId":"taskCheckpointTransmute","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint_id":{"type":"integer","description":"ID of the checkpoint to convert.","minimum":1}},"required":["checkpoint_id"]}}}},"responses":{"200":{"description":"Checkpoint 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 checkpoint with such an ID, or tracker to which checkpoint assigned is unavailable to current sub-user.
* 255 - Invalid task state - if any of checkpoints are not in unassigned or assigned state.

***

Changing `order` reorders all other checkpoints.

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 checkpoint

> Update a checkpoint. Pass a full checkpoint object including its \`id\`.\
> \
> \*\*\`tracker\_id\` is ignored\*\*: a checkpoint inherits its performer from its route.\
> \
> \`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.\
> \
> 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":{"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}}},"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/checkpoint/update":{"post":{"tags":["Tasks"],"summary":"Update checkpoint","description":"Update a checkpoint. Pass a full checkpoint object including its `id`.\n\n**`tracker_id` is ignored**: a checkpoint inherits its performer from its route.\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\nOnly a task in `unassigned` or `assigned` state can be changed. Anything else returns error 255.\n\nRequires the `task_update` right.","operationId":"taskCheckpointUpdate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint":{"allOf":[{"$ref":"#/components/schemas/TaskCheckpoint"}],"description":"The checkpoint to update, including its `id`. Read-only fields and `tracker_id` are ignored."},"create_form":{"type":"boolean","description":"Optional. Default `false`. When `true`, the `form_template_id` inside `checkpoint` is read and the form is created, replaced or deleted to match it."}},"required":["checkpoint"]}}}},"responses":{"200":{"description":"Checkpoint 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".


---

# 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/checkpoint.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.