Matters

A matter is the central organizing record for legal work in Clio Manage. Most billable work (activities, bills, documents, calendar entries, tasks) is associated with a matter, so integrations commonly spend time creating matters, finding the right one, or reading fields from it.

This guide covers common workflows: creating a matter, understanding its status and stages, identifying the people attached to it, finding matters with the list filters, and reading custom field values. For the full parameter and field reference, see the Matters API reference.

Creating a Matter

Create a matter by making a POST request to /api/v4/matters.json. Two fields are required: client (a Contact in Clio Manage, referenced by id) and description. A minimal request looks like this:

{
  "data": {
    "client": { "id": 1234 },
    "description": "Acme Corp - Series A financing"
  }
}

Other fields you may want to set on creation are:

Field	Type	Description
status	String	open, pending, or closed. See Matter Status.
practice_area	Object	The practice area, referenced by id. See Practice Areas.
responsible_attorney	Object	The responsible attorney, referenced by a User id. See People on a Matter.
originating_attorney	Object	The originating attorney, referenced by a User id.
responsible_staff	Object	A staff member assigned to the matter, referenced by a User id.
matter_stage	Object	The initial stage for the matter, referenced by id. See Matter Stages.
display_number	String	The matter's reference number. See Matter Numbering.
open_date	String	ISO-8601 date the matter was opened.
billable	Boolean	Whether the matter is billable. Defaults to true.
client_reference	String	A free-text reference string for tracking an external ID.

Nested records like client, practice_area, and responsible_attorney are passed as objects with an id, not as bare integers. All referenced records must already exist before you can attach them to a matter.

Matter Numbering

Clio Manage can number matters automatically or let you set the number yourself, and which mode an account is in changes how display_number behaves on creation. For background on how the numbering scheme works in the product, see the Matter Numbering Scheme help article.

• If the firm uses automatic matter numbering, leave display_number out and Clio assigns the next number. Passing your own value will be ignored.
• If the firm uses manual numbering, set display_number to the value you want.

If you need Clio to regenerate a matter's number according to the account's numbering scheme (for example, after the scheme changes or after updating fields the number is derived from), send reset_matter_number: true on an update.

Matter Status

A matter is always in one of three statuses:

Status	Meaning
open	The matter is active.
pending	The matter has been created but not yet opened.
closed	The matter has been closed.

When you list matters in the API, all matters are returned regardless of status. If you pass a status query parameter, only matters with the status specified in the parameter are returned. The status parameter accepts one or more statuses as a comma-separated list:

GET /api/v4/matters.json?status=open,pending

Note that a user can only see matters their Clio Manage role and permissions allow. If a matter is missing from the results even with the right status filter, confirm the authorizing user has access to it in the Clio web app.

To change a matter's status, PATCH the matter with a new status. Clio records the corresponding date (open_date, pending_date, or close_date), which you can also set explicitly:

{
  "data": {
    "status": "closed",
    "close_date": "2026-06-30"
  }
}

Matter Stages

Stages are a separate concept from status. Status is the fixed open/pending/closed lifecycle; stages are the customizable workflow steps a firm defines (for example "Intake", "Discovery", "Settlement"), and they're tied to a practice area. See the Matter Stages help article for product documentation.

List the stages available in the account with:

GET /api/v4/matter_stages.json

Set a matter's stage by passing matter_stage with the stage's id on create or update, and read the current stage back through the matter_stage field:

GET /api/v4/matters/{id}.json?fields=id,display_number,matter_stage{id,name}

One limitation to be aware of: the API exposes a matter's current stage, but not a full history of past stage changes. If you need to track stage transitions over time, subscribe to the matter updated webhook event with matter_stage included in the webhook's fields, and compare the value on each payload. See the Webhooks guide for setup details.

People on a Matter

The UI shows several roles for the people attached to a matter, and they map to distinct API fields. Getting these straight resolves a lot of "where is this field?" confusion:

UI label	API field	What it is
Responsible Attorney (Lawyer in CA, Solicitor in UK/EMEA)	responsible_attorney	The attorney accountable for the matter. A User.
Originating Attorney (Lawyer in CA, Solicitor in UK/EMEA)	originating_attorney	The attorney who brought in the matter. A User.
Responsible Staff	responsible_staff	A staff member assigned to the matter. A User.

All three reference Users (members of the firm), not Contacts. Each is settable on create or update by passing the object with an id, and each has a matching filter on the list endpoint (responsible_attorney_id, originating_attorney_id, and responsible_staff_id), so you can list every matter a given firm member is responsible for:

GET /api/v4/matters.json?responsible_attorney_id=567&status=open,pending,closed

Clients and other related people (opposing counsel, co-counsel, and so on) are Contacts rather than Users.

Related Contacts

The matter's primary client is set through the client field, but matters often involve other people too. Those are exposed as related contacts:

GET /api/v4/matters/{matter_id}/related_contacts.json?fields=id,name,type,is_matter_client,relationship{id,description}

Each entry returns the contact's name, type (Person or Company), an is_matter_client flag indicating whether they are also the matter's primary client, and a relationship object whose description field contains the role. This is a free-form text field set when the contact is added to the matter, so values vary (for example, "co-counsel" or "opposing counsel").

Multi-Client Matters

Clio Manage supports multi-client matters, where a matter has more than one client. The matter's client field always returns a single contact, the primary client:

GET /api/v4/matters/{id}.json?fields=id,display_number,client{id,name}

To retrieve every client on a matter, use the matter's contacts endpoint and keep the entries where is_client is true:

GET /api/v4/matters/{matter_id}/contacts.json?fields=id,name,type,is_client

The primary client is the entry whose id matches the matter's client_id; any other is_client entries are additional clients on the matter.

Practice Areas

Practice areas categorize matters (for example, Family, Criminal, or Corporate) and also drive which set of matter stages applies. Clio seeds new accounts with a default list, but firms can create and manage their own. List the practice areas defined in the account with:

GET /api/v4/practice_areas.json

Assign one to a matter by passing practice_area with its id on create or update, and filter the matters list by practice_area_id. See the Practice Areas API reference for the full endpoint.

Finding Matters

The list endpoint, GET /api/v4/matters.json, supports a broad set of filters. Combine them to narrow results to exactly the matters you need. The most useful are:

Filter	Finds matters…
client_id	for a specific client Contact.
status	with a given status (comma-separated open, pending, closed).
practice_area_id	in a given practice area.
responsible_attorney_id	with a given responsible attorney.
originating_attorney_id	with a given originating attorney.
responsible_staff_id	with a given staff member assigned.
query	matching a wildcard search over display_number, number, and description.
updated_since	changed after an ISO-8601 timestamp, useful for incremental syncs.
custom_field_values	with a given custom field value. See Custom Fields on a Matter.

Remember that the list endpoint is paginated. To retrieve every matching matter, follow the meta.paging.next URL until it's absent; see How do I retrieve all records across pages? for the full pattern.

Custom Fields on a Matter

Custom fields are how firms store data Clio doesn't model natively: a USCIS receipt number, a referral source, an internal case code. They're returned under the custom_field_values association, which is not included by default; you have to request it through the fields parameter, and because it's a nested association you select the sub-fields you want inside braces:

GET /api/v4/matters/{id}.json?fields=id,display_number,custom_field_values{id,field_name,value,custom_field}

Each entry pairs a value with the custom_field it belongs to. The shape of value depends on the field's type (text, number, date, picklist, and so on). Requesting field_type alongside value makes that explicit; note that each value's id is a composite string of the field type and the underlying id, not a plain integer:

GET /api/v4/matters/{id}.json?fields=id,display_number,custom_field_values{id,field_name,field_type,value}

{
  "data": {
    "id": 1001,
    "display_number": "2024-001",
    "custom_field_values": [
      {
        "id": "text_line-55001",
        "field_name": "USCIS Receipt Number",
        "field_type": "text_line",
        "value": "MSC2490012345"
      },
      {
        "id": "date-55002",
        "field_name": "Filing Deadline",
        "field_type": "date",
        "value": "2025-03-31"
      }
    ]
  }
}

To find matters by a custom field's value rather than read them off a single matter, use the custom_field_values filter on the list endpoint. It takes the custom field's id and the value to match:

GET /api/v4/matters.json?custom_field_values[12345]=A12345678

You can also restrict which custom fields are returned (without filtering the matters themselves) using custom_field_ids[], which is handy when a matter has many custom fields but you only care about a few.

Updating and Deleting Matters

The matter endpoint supports the standard set of operations:

Operation	Request
List matters	GET /api/v4/matters.json
Fetch a single matter	GET /api/v4/matters/{id}.json
Create a matter	POST /api/v4/matters.json
Update a matter	PATCH /api/v4/matters/{id}.json
Delete a matter	DELETE /api/v4/matters/{id}.json

When updating, send only the fields you're changing. Deleting a matter is a destructive operation that removes the matter and is rarely what you want; to take a matter out of active workflows, set its status to closed instead.