Create a task in a task plan

Required add-on
The company must have the ADVANCED APIS add-on enabled. Without it, the endpoint returns 403.

Input parameters — Required

Sent in the request body.

Parameter	Type	Required	Description
`description`	string	Yes	Task description. Minimum 3 characters, maximum 200. Cannot be empty.
`id_task_type_main`	integer	Yes	Main task type. Must exist in the company's main task type catalog.
`id_group_task`	integer	Yes	ID of the task plan where the task will be created. The plan must exist and be active.
`triggers`	array	Yes	Array of triggers. Minimum 1. See structure below.

`triggers` structure

Each trigger must include id_task_trigger_type and the conditional fields based on its type.

Field	Type	Required	Description
`id_task_trigger_type`	integer	Yes	`1` = DATE · `2` = READING_WHEN · `3` = READING_EVERY · `4` = EVENT
`value_main`	decimal	Conditional	DATE: > 0 (every how many periods). READING_EVERY: > 0. READING_WHEN: value to compare.
`id_period_date`	integer	Conditional	Required if type = `1` (DATE). Defines the frequency (days/weeks/months/years).
`id_replay`	integer	Conditional	Required if type = `1` (DATE). `2` = repeat by number.
`value_end`	decimal	Conditional	Required and > 0 if `id_replay = 2`. Number of repetitions.
`id_unit`	integer	Conditional	Required for READING_WHEN (2) and READING_EVERY (3). Must exist in `companies.units`.
`id_unit_operator`	integer	Conditional	Required for READING_WHEN (2). Comparison operator. Must exist in `companies.units_operators`.
`id_event`	integer	Conditional	EVENT (4): ID of an existing event in the company catalog, or use `event_description`.
`event_description`	string	Conditional	EVENT (4): event description; resolved to the catalog `id_event`. Required if `id_event` is not sent.

Trigger rules

Only 1 DATE trigger per task.

No duplicate units in READING_EVERY triggers.

Maximum 2 READING_WHEN per unit.

No duplicate events in EVENT triggers.

Input parameters — Optional

Parameter	Type	Default	Description
`id_task_type`	integer	—	Classification 1. Must exist in the task type catalog.
`id_task_type_2`	integer	—	Classification 2. Must exist in the task type catalog (level 2).
`id_priorities`	integer	`3` (MEDIUM)	Task priority. Must exist in `companies.priorities`.
`duration`	integer	`600`	Estimated duration in seconds. Minimum `60`.
`stop_assets_sec`	integer	`0`	Asset downtime in seconds.
`subtasks`	array	`[]`	Array of subtasks. See structure below.
`resources`	array	`[]`	Array of resources. See structure below.

`subtasks` structure

Field	Type	Required	Description
`description`	string	Yes	Subtask description.
`id_task_form_item_type`	integer	Optional	Field type `1`–`8`. Default `1`. `5` = METER_READING · `7` = DROPDOWN.
`id_unit`	integer	Conditional	Required if type = `5` (METER_READING). Must exist in `companies.units`.
`dropdown_options`	array	Conditional	Required if type = `7` (DROPDOWN). Minimum 2 options.
`id_task_form_item_group`	integer	Optional	Group/part. Must exist in `tasks.tasks_form_items_groups`.

`resources` structure

Field	Type	Required	Description
`type`	integer	Yes	`1` = INVENTORY · `2` = HUMAN_RESOURCES · `3` = SERVICES
`id_resource`	integer	Yes	Resource ID by type: inventory (`inventories.items` tool/spare part) · HR (`companies.hourly_rates`) · services (`third_parties.service_types`).
`qty`	numeric	Yes	Quantity. Must be > 0.
`unit_cost`	numeric	Yes	Unit cost. Must be > 0. `total_cost` is calculated automatically (`qty × unit_cost`).

Output parameters

Successful response: HTTP 201. Data is returned inside data.

Parameter	Type	Description
`id`	integer	ID of the created task.
`id_group_task`	integer	ID of the plan it belongs to.
`description`	string	Task description.
`id_task_type_main`	integer	Main type.
`id_task_type` / `id_task_type_2`	integer	Classifications.
`id_priorities`	integer	Priority.
`duration`	integer	Duration in seconds.
`stop_assets`	boolean	`true` if `stop_assets_sec > 0`.
`stop_assets_sec`	integer	Asset downtime in seconds.
`is_configured`	boolean	`false` if the task requires additional configuration from the UI.
`config_pending`	boolean	`true` when there are READING_WHEN/READING_EVERY triggers and the plan already has assets (meters need linking).
`date_create`	string	Creation date ISO 8601.
`triggers`	array	Created triggers, with generated IDs.
`subtasks`	array	Created subtasks.
`resources`	array	Created resources.

is_configured and config_pending
When the task has reading triggers (READING_WHEN or READING_EVERY) and the plan already has associated assets, the task is created successfully but returns "is_configured": false and "config_pending": true. Additional configuration is required to link meters to the plan's assets.

Errors

Code	Cause
`401`	Not authenticated · missing `auth` · invalid company · invalid user.
`403`	The company does not have the ADVANCED APIS add-on, or the user lacks ADD permission on Task Plans.
`400`	Missing `body` · validation failed (required fields, ranges, types) · plan not found or inactive · resource/unit/event not found in catalog.
`201`	Task created successfully (atomic operation).
`500`	Internal server error.

Comparison with `tasks_nonscheduled_post`

Aspect	`tasks_nonscheduled_post` (unscheduled task)	`tasks_plan_post` (this endpoint)
Context	Standalone / unscheduled task	Task inside a task plan (`id_group_task`)
Triggers	No	Yes — minimum 1 (DATE / READING_WHEN / READING_EVERY / EVENT)
Subtasks	Yes	Yes (optional)
Resources	Yes	Yes (optional)
Add-on	—	ADVANCED APIS

Example

Request body

{
  "description": "Monthly motor inspection",
  "id_task_type_main": 1,
  "id_group_task": 1024,
  "id_priorities": 3,
  "duration": 600,
  "stop_assets_sec": 0,
  "triggers": [
    {
      "id_task_trigger_type": 1,
      "value_main": 1,
      "id_period_date": 2,
      "id_replay": 1
    },
    {
      "id_task_trigger_type": 3,
      "id_unit": 5,
      "value_main": 500
    }
  ],
  "subtasks": [
    {
      "description": "Check oil level",
      "id_task_form_item_type": 3,
      "is_required": true
    },
    {
      "description": "Hour meter reading",
      "id_task_form_item_type": 5,
      "id_unit": 5
    }
  ],
  "resources": [
    {
      "type": 1,
      "id_resource": 312,
      "qty": 2,
      "unit_cost": 15.50
    }
  ]
}

Response `201`

{
  "success": true,
  "message": "201",
  "data": {
    "id": 88210,
    "id_group_task": 1024,
    "description": "Monthly motor inspection",
    "id_task_type_main": 1,
    "id_priorities": 3,
    "duration": 600,
    "stop_assets": false,
    "stop_assets_sec": 0,
    "is_configured": true,
    "config_pending": false,
    "date_create": "2026-06-24T10:00:00",
    "triggers": [
      { "id": 4501, "id_task_trigger_type": 1 }
    ],
    "subtasks": [
      { "id": 7701, "description": "Check oil level" }
    ],
    "resources": [
      {
        "id": 9901,
        "type": 1,
        "id_resource": 312,
        "qty": 2,
        "unit_cost": 15.50,
        "total_cost": 31.00
      }
    ]
  },
  "total": 1
}

Required add-on

Input parameters — Required

triggers structure

Trigger rules

Input parameters — Optional

subtasks structure

resources structure

Output parameters

is_configured and config_pending

Errors

Comparison with tasks_nonscheduled_post

Example

Request body

Response 201

`triggers` structure

`subtasks` structure

`resources` structure

`is_configured` and `config_pending`

Comparison with `tasks_nonscheduled_post`

Response `201`