Create task

Endpoint

POST /bot/forms/{form_id}/tasks

Creates a task in a form that the bot user can access.

Auth

Authorization: Bearer <token>
Content-Type: application/json

Path params

• form_id - target form ID

Minimal create task example

Minimal working payload:

{
  "task_items": [
    {
      "form_field_id": 101,
      "form_field_type": "TextField",
      "value": "Lead from bot"
    }
  ]
}

Example curl:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task_items": [
      {
        "form_field_id": 101,
        "form_field_type": "TextField",
        "value": "Lead from bot"
      }
    ]
  }' \
  https://public-api.hcapp.ee/bot/forms/12/tasks

Example with responsible_ids

For forms with steps, responsible_ids is required.

{
  "responsible_ids": [45],
  "task_items": [
    {
      "form_field_id": 101,
      "form_field_type": "TextField",
      "value": "Lead with responsible"
    }
  ]
}

Example with files

Upload files first via POST /bot/files/upload, then send returned file_id values.

{
  "files": [9001, 9002],
  "task_items": [
    {
      "form_field_id": 101,
      "form_field_type": "TextField",
      "value": "Request with attachments"
    }
  ]
}

Example with TableField

{
  "task_items": [
    {
      "form_field_id": 104,
      "form_field_type": "TableField",
      "value": [
        {
          "position": 1,
          "items": [
            {
              "form_field_id": 201,
              "form_field_type": "TextField",
              "value": "Product A"
            },
            {
              "form_field_id": 202,
              "form_field_type": "NumberField",
              "value": "2.5"
            }
          ]
        }
      ]
    }
  ]
}

Request body

Main request fields:

• responsible_ids: number[]
• participants_ids: number[]
• task_items: []
• files: number[]

It also accepts:

• parent_task_id
• parent_tasks_ids
• finish_parent_tasks
• tags
• files_data

These fields currently do not affect task creation through the bot API.

Request body fields

• responsible_ids list of responsible user IDs
• participants_ids participant user IDs, max 5
• files list of file_id, max 10
• task_items task items, max 50

Each simple item in task_items uses:

{
  "form_field_id": 101,
  "form_field_type": "TextField",
  "value": "Lead from bot"
}

For FormField, linked_task_id may also be provided.
For TableField, the value is an array of rows with position and nested items.

responsible_ids behavior

• If the form has steps, responsible_ids is required
• If one valid responsible is provided:
  • task.responsible_id is assigned directly
  • the task is assigned directly to one responsible user
• If multiple valid responsible IDs are provided:
  • a group assignment is created
  • task.responsible_id stays null
• Assignments are not returned in the response
• Responsible notifications are created asynchronously and do not change the response payload

Important response detail: responsible_ids in the response is built only from task.responsible_id.
For group assignment, the response does not echo the original list.

Response body

{
  "success": true,
  "error_message": null,
  "data": {
    "task_id": 5001,
    "form_id": 12,
    "title": "Lead #5001 Request with attachments",
    "author_id": 77,
    "responsible_id": 45,
    "responsible_ids": [45],
    "created_at": "2026-03-29T10:00:00+00:00",
    "last_activity": "2026-03-29T10:00:00+00:00",
    "is_finished": false,
    "status": "new",
    "due_date_at": null,
    "step_id": 3,
    "items": []
  }
}

Errors

• 403 Form access not found
• 404 Form not found
• 400 responsible_ids is required for forms with steps
• 400 Responsible users are invalid for this form
• 400 Form field {id} not found
• 400 Field {id} type mismatch: expected ..., got ...
• 400 Table child field {id} not found
• 400 Files not found: [...]
• 413 Payload too large. Max size is 131072 bytes

Limits

• JSON payload up to 128 KB
• participants_ids <= 5
• task_items <= 50
• files <= 10
• table rows <= 100
• row items <= 15