Create tasks and child tasks with a hub key

This page covers creating and following a case's tasks and child tasks with a hub key. Paths are under https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.

Calls

Creating a task

GET /tasks/templates lists your published task templatesTemplate A reusable feed post, form, e-sign, note or task kept in the Library and copied onto cases., oldest first, with each one's asset_id, title, description, due_mins (how many minutes after it's added it's due), rrule (its repeat), notifications, role_participants (the roles it's assigned to) and subtasks_ct (its child tasks).

POST /tasks takes:

• A task template brings its files, description, reminders, child tasks, and its assignees: the people on the case who hold its roles. It doesn't bring its title, due time or repeat: work out due_date from due_mins, and send its rrule if it has one.
• Copying a task on this case brings its files, description, reminders and child tasks, without any assignees, so send participants_ids to publish it.

curl -X POST https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Send your pay stubs", "duration": {"due_date": "2026-10-09T17:00:00-04:00"}, "participants_ids": ["cu-4f1c2a9e8b7d60"], "notifications": {"names": ["days"], "values": [-1440]}, "published": 1}'

It answers 201 with the task_id.

What happens next

When a task is published:

• Each assignee is emailed a request, or texted if they have no confirmed email, at once, unless instant_notify is false. It appears on their To DoTo Do The list on a case of things waiting for you, such as forms to fill in, documents to sign or events to confirm. and in their portal notifications.
• Reminders go out at each time in notifications still ahead. The task stays on each assignee's To Do, and keeps reminding them, until it's marked Done.
• A repeating task moves to its next date at each due date, and goes back to To Do. Its people are asked again at once, unless instant_notify is false.
• With child tasks, each person gets one message at a time, listing the task and the child tasks they're on, for the first request, each reminder and each repeat. The copy the case's staff get lists everything, with who each one waits on. A task from a template sends its first request once its child tasks are copied.
• A task whose due date has passed can't be published.
• A task with nobody assigned can't be published: leaving out participants_ids, or using a template whose roles nobody on the case holds, is refused with 403 PublishRecipientsMissingException, and nothing is saved. Assign someone, or save it as a draft.

A draft, with its child tasks, is on nobody's To Do and tells nobody. Publish it later with PUT /tasks/<task_id> and {"published": 1}, once someone is assigned, or with participants_ids in the same request. A published task can't go back to a draft.

Changing a task

PUT /tasks/<task_id> takes name, duration, participants_ids, description, notifications and instant_notify, and changes only the ones you send. Send duration whole: leaving out rrule ends the repeat. Leaving out zoneinfo keeps the time zone the repeat already has.

• People you add are told at once, in one message listing the task and the child tasks they're on, unless instant_notify is false: then they hear at its reminders. People already told aren't told again, and nor is someone you add to a child task of an open task they're on.
• Changing a published task's due date, repeat or reminders sends its request again, at once, to everyone it and its open child tasks are waiting on, people added in the same request included, unless instant_notify is false. Each person gets one message, listing the task and the child tasks they're on.
• DELETE /tasks/<task_id> deletes the task with its child tasks and comments, and takes it off everyone's To Do. Nobody is told.

Status

Only a task's assignees set its status, in the portal: todo, inprogress or done. A key can't set it. The task's status holds the latest, and completed_on is set when it's Done. GET /tasks/<task_id>/responses shows who set it and when. A Done or In Progress task whose due date you change goes back to todo, loses completed_on and its answer, and /responses lists nothing until someone sets its status again.

A task can't be marked Done while any of its published child tasks is open: the assignee is refused with 403 TaskSubtasksOpenException, whose reason lists them. A draft child task doesn't count. Reopening a child task, or adding or publishing one, under a Done task sets the task back to todo and clears its answer.

When an assignee marks a task Done, the staff on the case are told, as they would be if they'd created it themselves.

Comments

POST /tasks/<task_id>/comments takes message, up to 20,000 characters, and answers 201 with the comment_id. Write <@user_id> to mention someone. A comment with no mention reaches the task's assignees; one with mentions reaches only the people mentioned. A key can change only its own comments, and can delete any.

Child tasks

POST /tasks/<task_id>/subtasks adds a child task to a task:

• A child task is due with its main task, moves when the main task's due date does, and is reminded at the main task's times until it's Done. duration and instant_notify aren't needed; any you send are ignored.
• Once the main task's due time has passed, a child task can't be published: it's refused with 403 PublishSubtaskDueTimePassedException. Move the main task's due date first.
• Its assignees are asked in the main task's request, which lists it. A child task published after that request went, or someone added to it later, gets its own request, at once only if the main task's is, except for people the open main task is still asking. Its assignees can open it even if they aren't on the main task.
• A task holds at most 50 child tasks, a template's included. The 51st is refused with 403 SubtaskLimitReachedException.
• Under a draft main task, a child task sent with published 1 waits as a draft, as a template's child tasks do. It's published with the main task.
• GET /tasks/<task_id>/subtasks lists all of a task's child tasks at once, in the task's order, each with its subtask_id, name, participants_ids, status and due_date.
• Its comments are under /subtasks/<subtask_id>/comments, not under /tasks, and its files under /subtasks/<subtask_id>; see Upload and attach files with a hub key.

The AI suggestions for child tasks are for people in the portal: a key is refused with 403 BotNotAllowedException.

Listing tasks

GET /tasks needs filter:

Each task holds its task_id, name, status, participants_ids, due_date, duration, rrule, zoneinfo, published, completed_on, subtasks_ct and subtasks_order, its files under media, and its comment counts.

If a call is refused

For the error body and the rest of the codes, see Handle API errors and status codes.