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

# Schedule proposals

A preview of the tasks and routes a schedule will create over a date range.

A proposal is a preview: it reports the tasks and routes that the [schedules](/docs/navixy-api/user-api/resources/field-service/task/schedule.md) would create over a date range, without creating any of them. It answers what next week looks like before next week arrives.

Every filter is optional. Leaving `trackers`, `filter`, `from`, or `to` out, or sending it as null, simply drops that condition rather than matching nothing.

## API actions

API base path: `/task/schedule/proposal`.

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

If `trackers`, `filter`, `from` or `to` is not passed or *null* then appropriate condition not used to filter results.

***

## List schedule proposals

> Preview the tasks and routes the schedules would create over a period. \*\*Creates nothing.\*\*\
> \
> \`from\` should not be in the past, and \`to\` should not be before \`from\`.\
> \
> A request with an empty body reports \`interval\` as the missing parameter. That is the internal name of the field holding both dates; the public parameters are \`from\` and \`to\`.

```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/schedule/proposal/list":{"post":{"tags":["Tasks"],"summary":"List schedule proposals","description":"Preview the tasks and routes the schedules would create over a period. **Creates nothing.**\n\n`from` should not be in the past, and `to` should not be before `from`.\n\nA request with an empty body reports `interval` as the missing parameter. That is the internal name of the field holding both dates; the public parameters are `from` and `to`.","operationId":"taskScheduleProposalList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","description":"Show tasks that would be created after this date."},"to":{"type":"string","description":"Show tasks that would be created before this date. Must be after `from`."},"trackers":{"type":"array","description":"Optional. IDs of the trackers the tasks would be assigned to.","items":{"type":"integer"}},"filter":{"type":"string","description":"Optional. Filter over schedule label and description."},"types":{"type":"array","description":"Optional. Which kind of record to preview.","items":{"type":"string","enum":["task","route"]}}},"required":["from","to"]}}}},"responses":{"200":{"description":"The tasks and routes that would be created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","description":"The proposed records, each shaped like the task it would become.","items":{"$ref":"#/components/schemas/Task"}}}}}}},"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"}}}}}}
```


---

# 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/schedule/proposal.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.