View / Create / Edit / Delete
Search tasks#
Searches tasks using flexible filters and returns basic information about each matching task together with its responses — without executors, observers, forms, photo reports and attachments. Use this endpoint to quickly find the tasks you need and then request full data from the export endpoint below —
/connector/rpc/task_export_with_photos — passing var_task_ids.- Deleted tasks and responses are included in the search results and are marked with
task_deleted/response_deleted. - Responses are also matched by the modification date of their linked form instances, so filtering by
var_response_modified_at_from/var_response_modified_at_toalso catches responses whose forms were updated in the period — convenient for incremental synchronization.
Request parameters:
| Request Parameter | Type | Description | Required |
|---|---|---|---|
| var_task_ids | Integer array | The array of task IDs. Make sure array braces {} are url encoded. Example: %7B162,163%7D | false |
| var_task_types | String array | The array of task types: COMMON, ROUTED, PHOTO_REPORT, SURVEY. Make sure array braces are url encoded. | false |
| var_task_sub_types | String array | The array of task sub types. Make sure array braces {} are url encoded. | false |
| var_task_statuses | String array | The array of task statuses: OPEN, IN_PROGRESS, CLOSED. Make sure array braces are url encoded. | false |
| var_task_rule_ids | Integer array | The array of generation rule IDs. Only tasks created by these rules are returned. Make sure array braces {} are url encoded. | false |
| var_task_application_ids | Integer array | The array of application IDs. Make sure array braces {} are url encoded. | false |
| var_task_created_date_from | Timestamp without time zone | The start of the task creation date range, formatted as a timestamp without a time zone. Example: 2024-05-20T00:00:00 | false |
| var_task_created_date_to | Timestamp without time zone | The end of the task creation date range, formatted as a timestamp without a time zone. | false |
| var_task_deadline_date_from | Timestamp without time zone | The start of the task deadline date range, formatted as a timestamp without a time zone. | false |
| var_task_deadline_date_to | Timestamp without time zone | The end of the task deadline date range, formatted as a timestamp without a time zone. | false |
| var_task_modified_at_from | Timestamp without time zone | The start of the task modification date range, formatted as a timestamp without a time zone. | false |
| var_task_modified_at_to | Timestamp without time zone | The end of the task modification date range, formatted as a timestamp without a time zone. | false |
| var_response_statuses | String array | The array of response statuses. Make sure array braces {} are url encoded. | false |
| var_response_ids | Integer array | The array of response IDs. Make sure array braces {} are url encoded. | false |
| var_response_modified_at_from | Timestamp without time zone | The start of the response modification date range, formatted as a timestamp without a time zone. | false |
| var_response_modified_at_to | Timestamp without time zone | The end of the response modification date range, formatted as a timestamp without a time zone. | false |
Examples
200 OK
Get tasks with responses and attachments#
Returns tasks matching the query params together with their responses, executors, observers, linked form instances, photo report categories and executor attachments.
- The amount of data returned by this endpoint is usually quite large, so we strongly recommend limiting the export period with
var_task_modified_at_from/var_task_modified_at_toas much as possible, or first finding the tasks you need with the lightweight Search tasks endpoint and then exporting them byvar_task_ids. - Use
var_deletedto control whether deleted tasks and responses are returned. Deleted rows are marked withtask_deleted/response_deleted. - Set
var_show_empty_form_templatestotrueto also include form templates that are configured for a response but not yet filled, as empty entries inform_instances_by_templates.
Request parameters:
| Request Parameter | Type | Description | Required |
|---|---|---|---|
| var_task_ids | Integer array | The array of task IDs. Make sure array braces {} are url encoded. Example: %7B162,163%7D | false |
| var_task_types | String array | The array of task types: COMMON, ROUTED, PHOTO_REPORT, SURVEY. Make sure array braces are url encoded. | false |
| var_task_sub_types | String array | The array of task sub types. Make sure array braces {} are url encoded. | false |
| var_task_statuses | String array | The array of task statuses: OPEN, IN_PROGRESS, CLOSED. Make sure array braces are url encoded. | false |
| var_task_rule_ids | Integer array | The array of generation rule IDs. Only tasks created by these rules are returned. Make sure array braces {} are url encoded. | false |
| var_task_application_ids | Integer array | The array of application IDs. Make sure array braces {} are url encoded. | false |
| var_task_created_date_from | Timestamp without time zone | The start of the task creation date range, formatted as a timestamp without a time zone. Example: 2024-05-20T00:00:00 | false |
| var_task_created_date_to | Timestamp without time zone | The end of the task creation date range, formatted as a timestamp without a time zone. | false |
| var_task_deadline_date_from | Timestamp without time zone | The start of the task deadline date range, formatted as a timestamp without a time zone. | false |
| var_task_deadline_date_to | Timestamp without time zone | The end of the task deadline date range, formatted as a timestamp without a time zone. | false |
| var_task_modified_at_from | Timestamp without time zone | The start of the task modification date range, formatted as a timestamp without a time zone. | false |
| var_task_modified_at_to | Timestamp without time zone | The end of the task modification date range, formatted as a timestamp without a time zone. | false |
| var_response_statuses | String array | The array of response statuses. Make sure array braces {} are url encoded. | false |
| var_response_ids | Integer array | The array of response IDs. Make sure array braces {} are url encoded. | false |
| var_response_modified_at_from | Timestamp without time zone | The start of the response modification date range, formatted as a timestamp without a time zone. | false |
| var_response_modified_at_to | Timestamp without time zone | The end of the response modification date range, formatted as a timestamp without a time zone. | false |
| var_deleted | Boolean | When set, filters by whether the task and its response are deleted. Omit to return both active and deleted tasks. | false |
| var_show_empty_form_templates | Boolean | When true, form templates configured for a response but not yet filled are included as empty entries in form_instances_by_templates. Default: false | false |
Examples
200 OK
200 OK
Create task#
Creates a new task.
Request body:
| Attribute | Type | Description | Nullable |
|---|---|---|---|
| name | String | Task name | false |
| taskType | Enum of string | Type of the task. Available types: COMMON, SURVEY, PHOTO_REPORT | false |
| description | String | Task description | false |
| deadlineDate | Timestamp in milliseconds | Task deadline date | false |
| executors | Object | Object that defines who the task is assigned to: the executor role and the mapping of store (object) ids to user ids. See Executors object | false |
| executorsCommentRequired | Boolean | Whether the executor is required to leave a comment | false |
| needApproval | Boolean | Whether the task requires approval after completion | false |
| isLoadPhotoFromGalleryProhibited | Boolean | Prohibit uploading photos from the gallery | false |
| notificationPeriod | Enum of string | Frequency of reminders for executors: daily, weekly, deadline, dayBeforeDeadline | false |
| minAttachmentsCount | Integer | Minimum number of attachments the executor must add | false |
| notifications | List objects | Custom notification settings for the task. See Notification object | true |
| customObservers | List objects | Custom observers for the task. See Observer object | true |
| observersEnabled | Boolean | Whether observers are enabled for the task | false |
| formTemplateId | String | Identifier of the survey template. Required for the SURVEY task type | true |
| taskCategories | List objects | Photo report categories. Filled in only for the PHOTO_REPORT task type — each category is a separate photo section the executor fills in. See Task category object. | true |
| priorityId | Integer | Identifier of the task priority: 1 — Urgent 2 — High 3 — Medium 4 — Low | true |
| deadlineTimeEnabled | Boolean | Whether to take the time part of deadlineDate into account, not only the date | true |
| plannedStartDate | Timestamp in milliseconds | Planned start date of the task | true |
| plannedStartTimeEnabled | Boolean | Whether to take the time part of plannedStartDate into account | true |
| startBeforePlannedStartDate | Enum of string | Whether the executor may start the task before plannedStartDate: YES, NO | true |
| withManyExecutors | Boolean | Controls how responses are created when a store (object) has several matching executors.true — a single shared response is created per store for all its executors, so the task needs to be completed only once (useful when the work is physical and has to be done once).false — a separate response is created for each executor, and every executor must complete their own (useful when each employee has to act individually, e.g. fill in a survey or report course completion). | true |
| sendMailToTaskExecutor | Boolean | Whether to send an email notification to the executor. Default: true | true |
| visibleFromDate | Timestamp in milliseconds | The date from which the task becomes visible to the executor | true |
Response
Returns Task object
Examples
200 OK
200 OK
Create task by shop code#
Creates a task for one or more stores identified by their shop code, instead of by internal store/user ids as in Create task. Executors are resolved automatically: for every resolved store, the active
SHOP-level user who supervises that store within one of the given businessDirections becomes the executor — the request fails with 400 Bad Request if any shop code doesn't match an active store, or if no such supervisor is found for a store.Request body:
| Attribute | Type | Description | Nullable |
|---|---|---|---|
| name | String | Task name | false |
| taskType | Enum of string | Type of the task. Available types: COMMON, SURVEY, PHOTO_REPORT | false |
| description | String | Task description | false |
| deadlineDate | Timestamp in milliseconds | Task deadline date | false |
| shops | String array | Shop codes of the stores to create the task for. Each code must match an active store | false |
| businessDirections | Integer array | Identifiers of business directions. For each store, the executor is the active SHOP-level user who supervises that store within one of these business directions | false |
| executorsCommentRequired | Boolean | Whether the executor is required to leave a comment | false |
| needApproval | Boolean | Whether the task requires approval after completion | false |
| isLoadPhotoFromGalleryProhibited | Boolean | Prohibit uploading photos from the gallery | false |
| notificationPeriod | Enum of string | Frequency of reminders for executors: daily, weekly, deadline, dayBeforeDeadline | false |
| minAttachmentsCount | Integer | Minimum number of attachments the executor must add | false |
| notifications | List objects | Custom notification settings for the task. See Notification object | true |
| customObservers | List objects | Custom observers for the task. See Observer object | true |
| observersEnabled | Boolean | Whether observers are enabled for the task | false |
| autoAssignObservers | Boolean | Whether to automatically add each executor's direct supervisor as an observer, in addition to customObservers | true |
| formTemplateId | String | Identifier of the survey template. Required for the SURVEY task type | true |
| taskCategories | List objects | Photo report categories. Filled in only for the PHOTO_REPORT task type — each category is a separate photo section the executor fills in. See Task category object. | true |
| taskResponseCategoryLinks | List objects | Alternative, per-store way to define PHOTO_REPORT categories: each entry pairs a store's shopSap with a categoryName and an optional externalUrl reference link. Referenced stores are automatically added to shops, and a matching entry is added to taskCategories for every distinct category name that isn't already there | true |
| priorityId | Integer | Identifier of the task priority: 1 — Urgent 2 — High 3 — Medium 4 — Low | true |
| deadlineTimeEnabled | Boolean | Whether to take the time part of deadlineDate into account, not only the date | true |
| withManyExecutors | Boolean | Controls how responses are created when a store (object) has several matching executors.true — a single shared response is created per store for all its executors, so the task needs to be completed only once (useful when the work is physical and has to be done once).false — a separate response is created for each executor, and every executor must complete their own (useful when each employee has to act individually, e.g. fill in a survey or report course completion). | true |
| sendMailToTaskExecutor | Boolean | Whether to send an email notification to the executor. Default: true | true |
| attachments | String array | URLs of files to download and attach to the task right after it is created | true |
Response
Returns Task object
Examples
200 OK
Edit task#
Updates an existing task. Only the fields you provide are updated — omitted fields keep their current values.
Request body:
| Attribute | Type | Description | Nullable |
|---|---|---|---|
| id | Integer | Task identifier | false |
| name | String | Task name | false |
| description | String | Task description | false |
| deadlineDate | Timestamp in milliseconds | Task deadline date | false |
| deadlineTimeEnabled | Boolean | Whether to take the time part of deadlineDate into account, not only the date | true |
| plannedStartDate | Timestamp in milliseconds | Planned start date of the task | true |
| plannedStartTimeEnabled | Boolean | Whether to take the time part of plannedStartDate into account | true |
| startBeforePlannedStartDate | Enum of string | Whether the executor may start the task before plannedStartDate: YES, NO | true |
| priorityId | Integer | Identifier of the task priority: 1 — Urgent 2 — High 3 — Medium 4 — Low | true |
| newResponses | Object | New executors to add to the task — existing responses are not affected. See Executors object | true |
| notifications | List objects | Custom notification settings for the task. See Notification object | true |
| customObservers | List objects | Custom observers for the task. See Observer object | true |
| executorsCommentRequired | Boolean | Whether the executor is required to leave a comment | false |
| needApproval | Boolean | Whether the task requires approval after completion | false |
| signatureRequired | Boolean | Whether a digital signature is required to close the task | false |
| isLoadPhotoFromGalleryProhibited | Boolean | Prohibit uploading photos from the gallery | false |
| notificationPeriod | Enum of string | Frequency of reminders for executors: daily, weekly, deadline, dayBeforeDeadline | false |
| minAttachmentsCount | Integer | Minimum number of attachments the executor must add | false |
| taskCategories | List objects | Photo report categories. Filled in only for the PHOTO_REPORT task type — each category is a separate photo section the executor fills in. The update merges categories by id: existing categories are updated, new ones are added, and categories whose id is omitted are removed. See Task category object. | true |
| deleteResponses | Integer array | Identifiers of responses to delete from the task | true |
| delegationEnable | Boolean | Whether the executor can delegate the task to another user | true |
| editorId | Integer | Identifier of the editor. Falls back to the current user if not provided | true |
| returnClosedResponses | Boolean | Whether to return closed responses back to work | true |
| applicationSourceFileUid | String | Identifier of the application source file | true |
| formTemplateId | String | Identifier of the survey template for SURVEY tasks without an application | true |
| customData | String (JSON) | Custom data in raw JSON format | true |
| visibleFromDate | Timestamp in milliseconds | The date from which the task becomes visible to the executor | true |
Response
Returns Task object
Examples
200 OK
200 OK
Delete task#
Returns code status
Examples
200 OK