How to apply a Clio task template to a matter through the API

There are two versions of this job and they have different answers. Most of the confusion, including ours, comes from assuming they are the same thing.

Applying a whole template list to a matter

Clio’s interface has a button for this, and the natural assumption is that there is a matching endpoint on the task template resource. There is not. Nothing under /task_template_lists will assign anything to a matter, and no path in Clio’s spec contains “apply”.

It is done from the matter instead. Both POST /matters.json and PATCH /matters/{id}.json accept a nested array:

task_template_list_instances[]:
  task_template_list : { id }   required on POST
  assignee_id        : the user the list is assigned to
  notify_assignees    : whether assignees get notified
  due_at             : ISO-8601 date (format: date, not date-time)

Enter fullscreen mode Exit fullscreen mode

Those are the only two operations in the API that accept it. Note the asymmetry: on POST /matters.json the task_template_list object is required, and on PATCH /matters/{id}.json the item schema marks nothing as required at all.

POST /task_template_lists/{id}/copy.json exists and sounds like the thing you want. It is not. It duplicates a list into another list, takes name, description and practice_area (all optional), and has no matter parameter.

The two problems that will actually cost you time

Instances are write-only. task_template_list_instances appears in those two request bodies and nowhere in the matter response schema. So there is no documented way to ask “does this matter already have the list on it?” You verify by fetching /tasks.json filtered to the matter and matching on names, which is uglier than it sounds and is most of the reconciliation work.

Which makes idempotency your problem. If your automation fires the PATCH twice, nothing in the API stops you assigning the checklist twice. For anything triggered off matter creation or a stage change, decide up front how you detect an already-applied list, because the readback above is the only tool you have.

Between them, those two are roughly half the build. Scope accordingly: with the trigger, the guard and the reconciliation this is a two to four day job. It looks like an afternoon.

Due dates, and what due_at actually seeds

Task template due dates are a chain, not a flat set of offsets. Each template carries cascading, cascading_source (the parent template it derives from), cascading_offset, cascading_offset_polarity (before or after the parent) and cascading_offset_type (CalendarDays, CalendarWeeks and so on). Templates with cascading: false carry no offset at all.

The due_at you pass on the instance seeds the root of that chain, and Clio resolves the rest.

Worth being precise about the consequence, because it is easy to overstate: you do not lose the cascade by building tasks yourself. POST /tasks.json exposes the same five fields, including cascading_source, described as the parent task used to determine the cascaded task’s due_at. So you can rebuild the chain manually by pointing each task at the one before it.

The honest difference is effort and fidelity, not capability. Using the instance means Clio resolves the chain from one date you supply. Building by hand means you reconstruct the parent relationships yourself and keep them correct as the template list changes. That is a real reason to prefer the instance and it is not the same as “you cannot do it.”

Creating one task from one template

Different job. Here you want a single task created from a single template, which is what you need when something in your own workflow decides a specific task is due.

POST /tasks.json has no template field of any kind. Its required fields are name, description and assignee, so nothing is inherited for you. Read the template and pass the fields explicitly:

GET  /api/v4/task_templates/{id}.json?fields=id,name,description,priority

POST /api/v4/tasks.json
{
  "data": {
    "matter":      { "id": <MATTER_ID> },
    "name":        "<template name>",
    "description": "<template description>",
    "priority":    "<template priority>",
    "assignee":    { "id": <USER_ID>, "type": "User" }
  }
}

Enter fullscreen mode Exit fullscreen mode

Three things worth knowing before you build it:

description is required, and templates can have an empty one. Copying an empty description straight across fails the call, so you need a fallback rather than passing through whatever the template holds. This one cost us a production run.

The assignee does not carry itself. We resolve it from the matter’s responsible_staff, falling back to responsible_attorney, and throw rather than guess when the matter has neither. Guessing is worse than failing loudly, because a task assigned to the wrong person looks done.

If you list templates, get the pagination right. /task_templates.json uses cursor paging and returns meta.paging.next as a full URL, not a token to append. Cursor paging also requires ordering by order=id(asc); without it you silently fall back to offset paging, which is capped at 10,000 records. Page size is 200, so this matters at real volume rather than on a single practice area’s list.

Which one you want

If your trigger is “a matter of this type was created and should get its standard checklist,” you want the list instance on the matter, passed at creation so the chain anchors correctly.

If your trigger is something your own code decided, a document arrived, a stage changed, a deadline moved, you want the single-task path, because there is no list involved and you are creating one task on purpose.

The expensive mistake is finding only the second path, concluding lists cannot be assigned through the API at all, and rebuilding every checklist task by task. That happens because the obvious place to look has nothing in it.

Endpoint shapes, field names and required flags above are from Clio’s published API reference and OpenAPI spec for Clio Manage v4, checked July 2026. The empty-description failure and the assignee handling are from our own production integration. Clio does not publish the error string for the first of those, so it is reported here as our observation rather than as documentation. If Clio changes any of this, believe the reference over this page.