Reading Clio custom fields in an automation

Custom fields are where the facts an automation needs live: the county, the case sub-type, whether there is real property, which office owns the matter. Clio Manage stores them, the Manage API both filters and reads them, and Clio's own automated workflows cannot use them as conditions, a workflow conditions on practice area and optionally responsible attorney, and that is all. So anything that branches on a custom field sits outside Clio.

This page is for whoever is building that: the vocabulary, the field types and what each supports, the exact API mechanics, and the five traps that make a rule fail silently rather than loudly.

The four words, kept straight

Two flags on the definition are worth knowing because they change what your automation can assume. A default field appears on every contact or matter form and may be left blank. A required field must be filled and cannot be blank. Making the fields your automation depends on required is the single cheapest reliability fix available to you.

Permissions: all users can add and remove custom fields on records, but only administrators can create, edit or delete the fields and field sets themselves.

Plan gate: custom fields are not available on Clio's entry tier. They start at Core and are present on Signature and Elite. (Clio's help centre still names the old tiers, Essentials, Advanced, Expand, for the same three.)

The field types, and what each one is good for

The highest-leverage decision in this whole area is made before any code exists: make the fields an automation will read picklists, not text fields. A text field asking for the county will contain four spellings within a month, and each one is a rule that silently does not match. A picklist with eight options cannot.

Clio's API documentation supports this directly: text and picklist fields match on equality only, while numeric, currency, date and time fields also support range comparisons. If you need "greater than", the type has to be one of the latter four, and that is a decision you make at field-creation time.

The API mechanics

Two distinct operations, and people conflate them.

Filtering matters by a custom field value. Use the custom_field_values filter on the matters list endpoint, keyed by the custom field's id, for example custom_field_values[12345]=A12345678. Note the key is the field id, not its name. Resolve names to ids once and cache the mapping.

Reading values back off a matter. Request the custom_field_values association through the fields parameter. If you do not ask for it, it is not in the response, and absent is indistinguishable from empty unless your code checks. This is the most common cause of "the rule worked yesterday": nothing changed except which fields the request asked for.

Related, and useful to know before you design around it: the API exposes a matter's current stage but not its stage-change history. If your automation needs to know that a matter moved from Discovery to Trial Prep rather than just that it is now in Trial Prep, you have to record that yourself as it happens. The three role fields map to responsible_attorney, originating_attorney and responsible_staff, and all three reference users, not contacts.

The five traps

1. The value-instance id is not the field id

The one that costs real money. A custom field value on a matter has its own id, separate from the field definition's id. Write an update using the definition id and Clio will either reject it or create a brand-new value instance alongside the existing one. Your batch reports success; you have duplicated the data rather than normalised it.

The procedure, and there is no shortcut that skips it: read the matter's current custom_field_values, capture the instance id for each value you intend to change, and write back to those exact ids. Dry-run any bulk write and diff the result before you trust it.

2. Empty and missing are different, and both look false

Three states hide behind one appearance:

• The field exists on this matter and holds a value.
• The field exists on this matter and is empty.
• The field is not on this matter at all, its field set belongs to a practice area this matter is not in.

Naive code treats all three as falsy. Fine for "include this task if the box is ticked", dangerous for anything else, because "no real property" and "nobody has looked yet" are opposite facts. A rule that cannot tell them apart will confidently produce the wrong task list on an incomplete matter, and incomplete matters are the normal state on day one. Decide explicitly what happens when the field is absent, and make that the loud path.

3. Field sets are scoped, so the field may not exist

Custom field sets are added to contacts or matters for a specific practice area. A rule branching on case sub-type works perfectly for probate and finds nothing for personal injury, because the field is not on those matters. Nothing errors; the branch just never fires. Test every rule against a matter in a practice area the field does not belong to, in production, that case is more common than the one you built for.

4. The field is not filled in when the trigger fires

A timing problem, not a data problem, and the hardest of the five. If your automation fires when the matter is created and the field it branches on is completed during intake, the rule reads an empty field and branches wrong.

Three honest fixes: mark the field required so it cannot be blank at creation; trigger on a later stage; or design the automation to hold and re-read rather than deciding once. Pick deliberately, this is the failure behind almost every "the automation created the wrong tasks" complaint.

5. Renaming a field or an option breaks reads by name

Field names and picklist option labels are editable, and nothing tells you what depends on them. Code that looks a field up by display name breaks on rename. Rules matching a picklist label break when the label is edited, and stop matching entirely when the option is deleted, with no error, because from the API's point of view the value simply is not there any more.

Match on ids, show labels to humans, and keep the mapping somewhere version-controlled so a rename appears in a diff rather than as a mystery. Getting option ids out of Clio has historically been awkward, which is exactly why people fall back to labels, do the work once anyway.

Designing fields you can automate on later

Most of the pain above is avoidable when the fields are created. Five rules we apply on every setup:

1. Anything a rule will read is a picklist. Free text is for humans, not conditions.
2. Anything a rule needs a range on is numeric, currency, date or time. Text and picklist match on equality only, and you cannot change a field's type later.
3. Mark the decisive fields required. It removes trap 4 outright, which is the most expensive of the five.
4. Never encode two facts in one field. Contested, with property should be two fields; one combined field means every new combination is a new option and every rule has to know all of them.
5. Write down which automations depend on which field. One page. It is the difference between a rename being a five-minute check and a fortnight of odd behaviour.

None of that is clever. All of it is cheaper than the alternative, and it costs nothing while the fields are still being created.

How Taskflow handles it

Taskflow reads Clio custom field values and uses them as branch and assignee-rule conditions, match a picklist option, a checkbox, a date or numeric range, with fields resolved by id rather than by name, so a rename does not silently detach a rule. Absent and empty are separate states you can branch on independently, and a rule can be marked as requiring a field so a matter missing it produces a visible run failure instead of a quietly wrong task list. The rules and matching documentation has the full condition set; different task lists for different case types is the same subject from the firm's side rather than the developer's.

Questions people also ask

Can Clio automated workflows use custom fields as conditions?

No. An automated workflow's conditions are practice area (required) and responsible attorney (optional). Custom fields are readable through the API but cannot be evaluated by the native automation.

How do you read custom field values from the Clio Manage API?

Request the custom_field_values association via the fields parameter on the matter. Omit it and the values are absent from the response entirely, which your code will probably read as empty.

How do you find matters by custom field value?

The custom_field_values filter on the matters list endpoint, keyed by the field's id: custom_field_values[12345]=A12345678. Text and picklist match on equality; numeric, currency, date and time also support ranges.

What custom field types does Clio support?

Picklist, checkbox, single-line text (255 chars), long text (64,000 chars), numeric (two decimals), currency (no symbols in the value), date, time, contact, matter, email and URL. Field names and picklist options are capped at 64 characters.

Can custom fields be required in Clio?

Yes. A field can be set as required, it must be filled and cannot be left blank, or as default, which puts it on every form but allows a blank. Required is the flag that matters for automation.

Do custom fields work on contacts as well as matters?

Yes. Custom fields and field sets attach to both contacts and matters. Matter fields are what automations usually branch on; a contact field is the right home for a fact about the client rather than the case.

Which Clio plans include custom fields?

Not the entry tier. Custom fields start one tier up and are included in the two above that, Core, Signature and Elite in Clio's current naming.

What happens to an automation when a picklist option is deleted?

Rules matching that option stop matching, silently. Deleting a picklist option is a change to your automation logic and deserves the same care as editing the rule itself.