Clio Matters git:20260728.b7e78fcA

Immutable. This exact content is served forever at /api/v1/blob/84ddf9dd9b973fc3.

---
name: "Clio Matters"
description: >
  Clio matters -- the case/client-file object that almost everything else
  in Clio hangs off of: the matter status lifecycle, linking a matter to a
  client contact, practice areas, custom fields, and matter numbering.
when_to_use: >-
  When creating, updating, searching, or summarizing a Clio matter, or when
  deciding what a matter's status means. Use when: clio matter, clio case,
  clio matter status, clio matter number, clio practice area, clio
  responsible attorney, or clio client matter.
---

# Clio Matters

## Overview

A **matter** is Clio's core object — the case or client file. It is the
hub that almost everything else in Clio (activities, tasks, communications,
documents, calendar entries, bills) references via `matter_id`. See the
[api-patterns skill](../api-patterns/SKILL.md) for the full matters-as-hub
picture and the deliberate v1 scope limits that apply across every domain.

Tools: `clio_matters_list`, `clio_matters_get`, `clio_matters_create`,
`clio_matters_update`. Navigate into the `matters` domain first
(`clio_navigate`) — these tools aren't visible until you do.

**No delete tool exists for matters.** A matter that shouldn't exist
anymore gets closed (status change), not removed — see below.

## Key Fields

A matter typically carries:

- **Client** — the contact (person or company) the matter is for. Every
  matter has exactly one client contact; see the
  [contacts skill](../contacts/SKILL.md) for how a contact can be party to
  many matters in different roles.
- **Responsible attorney** — the attorney of record on the matter
- **Status** — see lifecycle below
- **Practice area** — the area of law the matter falls under (e.g.
  Litigation, Real Estate, Family Law) — usually a firm-configured picklist
- **Matter number / display number** — Clio's human-readable matter
  identifier (distinct from the internal numeric ID)
- **Description** — free-text summary of what the matter is
- **Custom fields** — firm-specific fields configured in Clio; treat these
  as opaque key/value pairs unless the firm has told you what they mean

## Matter Status Lifecycle

Matters move through a small set of statuses. Typical values:

| Status | Meaning |
|---|---|
| Open | Active matter, currently being worked |
| Pending | Not yet fully active — e.g. awaiting engagement signature, conflict check, or intake completion |
| Closed | Matter has concluded — no more billable work expected |

Treat status as the primary signal for "is this matter live." When a user
asks for "my open matters" or "what's still active," filter on status
rather than trying to infer activity from recency of activities/tasks
alone — a matter can be quiet-but-open (waiting on a court date) or
closed-but-recently-touched (final billing cleanup).

**Closing a matter is a status update** (`clio_matters_update` with
`status: "Closed"`), not a delete. There is no way to remove a matter
through this integration — that's consistent with the no-delete-anywhere
rule and with legal records retention practice.

## Creating a Matter

Minimum viable create: a client contact and (usually) a responsible
attorney. Before calling `clio_matters_create`:

1. **Resolve the client contact first.** Search contacts
   (`clio_contacts_list` with a name/company filter) before creating a new
   one — duplicate client contacts are a real mess in a matter-centric
   system. See the [contacts skill](../contacts/SKILL.md).
2. **Confirm practice area and responsible attorney** if the firm uses
   them for routing/reporting — don't leave them blank silently if the
   user's context implies a specific practice group.
3. **Ask before guessing at custom fields.** Firm-specific custom fields
   often drive downstream automation (billing templates, conflict
   workflows) — don't populate them with assumptions.

## Updating a Matter

`clio_matters_update` — same shape as create, but scoped to an existing
`matter_id`. Common updates: status changes (open → pending → closed),
reassigning the responsible attorney, correcting the practice area, or
editing the description. There's no partial-vs-full-update ambiguity to
worry about here beyond the standard rule: only send the fields that are
actually changing plus the ID.

## Practice Area & Custom Field Considerations

- Practice areas are usually a closed, firm-configured list — if a value
  the user wants doesn't exist, say so rather than inventing a close match.
- Custom fields vary firm-to-firm and are not part of the fixed schema —
  when summarizing a matter for a user, surface custom fields you can read
  but don't assume you know what they mean without firm context.

## Linking a Matter to a Client Contact

The client relationship is set at creation (or via update) using the
contact's ID from `clio_contacts_list`/`clio_contacts_get`. A matter has
one client contact, but that contact may be party to many other matters —
always resolve by searching contacts rather than assuming a name is
unique; law firms frequently have multiple contacts with similar or
identical names across different matters.

## Related Skills

- [Clio API Patterns](../api-patterns/SKILL.md) — connection, navigation, matters-as-hub model, scope limits
- [Clio Contacts](../contacts/SKILL.md) — the client (and other-role) contacts linked to a matter
- [Clio Time & Billing](../time-billing/SKILL.md) — activities and bills scoped to a matter