# Clio Matters API

**Canonical:** https://apis.io/apis/clio/clio-matters-api/  
**Provider:** Clio — https://apis.io/providers/clio/  
**Base URL:** https://app.clio.com/api/v4  
**Documentation:** https://docs.developers.clio.com/

Clio Matters API is one of 85 APIs that [Clio](https://apis.io/providers/clio/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Matters. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, and authentication docs.

[Matters](https://help.clio.com/hc/en-us/articles/9285920226075-Clio-Manage-Matters-Overview) in Clio represent a firm’s cases. All relevant information—Bills, Documents, Time Entries, etc.—are contained in the Matter. A user’s ability to access a Matter is controlled by the [Matter Permission settings](https://help.clio.com/hc/en-us/articles/9286062516123-Matter-Permissions-and-Rates). A user without permission will be unable to view or update a Matter. [Support Link](https://help.clio.com/hc/en-us/articles/9285920226075-Clio-Manage-Matters-Overview) [Matters in Clio](http://app.clio.com/matters) ## Associations A Matter can be persisted with its associations in a single request. The followings detail the nested attributes to persist the associations. ### Custom Field Values A CustomFieldValue contains the value of a CustomField for a Matter. Below are some examples of how to create, read, update, and destroy the CustomFieldValues of a Matter: #### Create Note: The value of `id` used here is the value of the `id` parameter in the response received when [creating a new CustomField](https://docs.developers.clio.com/clio-manage/api-reference/#tag/Custom-Fields/operation/CustomField#create) or one returned in a [query of an existing CustomField](https://docs.developers.clio.com/clio-manage/api-reference/#tag/Custom-Fields/operation/CustomField#show). ```json Request PATCH /api/v4/matters/1.json { data: { custom_field_values: [ { custom_field: { id: 2 }, value: "Initial value" } ] } } ``` #### Read Note: The `id` of the CustomFieldValue is a composite value including the custom field type. Use this `id` to update and destroy the CustomFieldValue. The `id` of the associated Custom Field can be found by querying the `custom_field` for all CustomFieldValues related to the Matter, e.g.: `/api/v4/matters/1?fields=id,display_number,custom_field_values{id,value,custom_field}` Note: The `id` may be `NULL` when the CustomField is displayed by default but has not yet been given a value. ```json Request GET /api/v4/matters/1.json?fields=custom_field_values{id,value,custom_field} { data: { custom_field_values: [ { id: "text_line-1", value: "Current value", custom_field: { id: 2 } } ] } } ``` #### Update Note: The value of the CustomFieldValue `id` used here is a composite value and can be found by querying for all CustomFieldValues related to the Matter, e.g.: `/api/v4/matters/1?fields=id,display_number,custom_field_values{id,value,custom_field}` Note: If the `id` is `NULL`, you must provide `custom_field{id}` to create the CustomFieldValue and assign a value (see **Create**). ```json Request PATCH /api/v4/matters/1.json { data: { custom_field_values: [ { id: "text_line-1", value: "Updated value" } ] } } ``` #### Destroy Note: The value of the CustomFieldValue `id` used here is a composite value and can be found by querying for all CustomFieldValues related to the Matter, e.g.: `/api/v4/matters/1?fields=id,display_number,custom_field_values{id,value}` ```json Request PATCH /api/v4/matters/1.json { data: { custom_field_values: [ { id: "picklist-2", _destroy: true } ] } } ``` ### Custom Rates Each Matter can be set up to be billed on an Hourly basis, Flat Fee basis, or on Contingency. To set the rate type, assign `custom_rate[type]` with one of the values, `"HourlyRate"`, `"FlatRate"` or `"ContingencyFee"`. By default, a Matter is billed on an hourly basis. If the rate type is modified, the persisted rates will be deleted. [Support Link](https://help.clio.com/hc/en-us/articles/9289801180187) #### Hourly Rates Selecting the `"HourlyRate"` type will record time entries based on the custom hourly rates. A custom hourly rate can be associated to a User or a Group. Checkout the sample request to update the hourly rates of a Matter: ```json Request PATCH /api/v4/matters/1.json { data: { custom_rate: { type: "HourlyRate", rates: [ // update a rate for a user { id: 1, rate: 100, user: { id: 1 } }, // update a rate for a group { id: 2, rate: 100, group: { id: 1 } }, // create a rate for a user { rate: 100, user: { id: 2 } }, // create a rate for a group { rate: 100, group: { id: 2 } }, // destroy a rate { id: 3, _destroy: true } ] } } } ``` #### Flat Rate Selecting the `"FlatRate"` type will bill the matter with a flat fee. A Matter can only have one flat rate. For associated objects, you can specify `_destroy` attribute to delete the rate. Checkout the sample request to update the flat rate of a Matter: ```json Request PATCH /api/v4/matters/1.json { data: { custom_rate: { type: "FlatRate", rates: [ { id: 1, user: { id: 1 }, activity_description: { id: 1 }, rate: 100, } ] } } } ``` #### Contingency Fee Selecting the `"ContingencyFee"` type will specify a contingency fee percentage on a Matter and the award or settlement amount won at the completion of the case. A Matter can only have one definition of contingency fee. For associated objects, you can specify `_destroy` attribute to delete the rate. Contingency Fee Matters are not available to all plan types. See [here](https://www.clio.com/pricing/) for feature support across different plans. Checkout the sample request to update the contingency fee of a Matter: ```json Request PATCH /api/v4/matters/1.json { data: { custom_rate: { type: "ContingencyFee", rates: [ { id: 1, user: { id: 1 }, rate: 20, } ] } } } ``` ### Matter Budget Clio supports tracking a matter budget directly within a Matter. A Matter can only have one matter budget associated with it. A matter budget can not be added to flat rate matters. For associated objects, you can specify the `_destroy` attribute to delete the Matter Budget. Matter Budget are not available to all plan types. See [here](https://www.clio.com/pricing/) for feature support across different plans. Check out the sample request to update the matter budget of a Matter: ```json Request PATCH /api/v4/matters/1.json { data: { matter_budget: { budget: 5000000, include_expenses: true, notification_threshold: 100, notify_users: true users: [ { id: 1 }, // destroy { id: 2, _destroy: true } ] } } } ``` ### Grant Matter Clio supports associating a Grant with a Matter, using Grant Matters. A Matter can have up to three Grants (and Grant Matters) associated with it. For associated objects, you can specify the `_destroy` attribute to delete Grant Matters. Grant Matters are only for legal aid US customers Checkout the sample request to update a Grant Matter: ```json Request PATCH /api/v4/matters/1.json { data: { "grant_matters": [ {"id":{{existing_grant_matter_id}}} ] } } ``` ### Relationships There are people and/or companies related to a Matter other than the client of the lawyer. Clio helps define how the entities relate to a Matter. #### Please be advised that the use of the relationships field below is discouraged. We plan to deprecate it in the future. Please use [Relationships](https://docs.developers.clio.com/clio-manage/api-reference/#tag/Relationships) instead. Checkout the sample request to update Relationships of a Matter: ```json Request PATCH /api/v4/matters/1.json { data: { relationships: [ // update { id: 1, contact: { id: 1 }, description: "Opposing Counsel" }, // create { contact: { id: 2 }, description: "Judge" }, // destroy { id: 2, _destroy: true } ] } } ``` ### Statue Of Limitations Clio supports to track a Statute of Limitations date directly within a Matter. It can be associated with reminders as a Task. A Matter can only have one definition of Statue of Limitations. For associated objects, you can specify `_destroy` attribute to delete the Statue of Limitations. Check out the sample request to update the Statue of Limitations and its reminders of a Matter: ```json Request PATCH /api/v4/matters/1.json { data: { statue_of_limitations: [ due_at: "20201231", status: "open", reminders: [ // update { id: 1, duration_unit: "days", duration_value: 1, notification_method: { id: 1 } }, // create { duration_unit: "days", duration_value: 1, notification_method: { id: 2 } }, // destroy { id: 2, _destroy: true } ] ] } } ``` ### Task Template Lists Clio supports assigning task template lists to a matter from with the same request that creates or updates a matter. Please note that a task template list **can only be assigned**. Once a task template list is assigned, it **cannot be modified or destroyed**. Checkout the sample request to assign a task template list id to a matter: ```json Request PATCH /api/v4/matters/1.json { data: { task_template_list_instances: [ { notify_assignees: true, task_template_list: {id: 1}, }, { notify_assignees: false, task_template_list: {id: 2}, } ], } } ```

## Machine-readable artifacts (5)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/clio/refs/heads/main/openapi/clio-matters-api-openapi.yml
- **Documentation** — https://docs.developers.clio.com/
- **Reference** — https://docs.developers.clio.com/api-docs/
- **Authentication** — https://app.clio.com/oauth/authorize
- **GraphQL** — https://raw.githubusercontent.com/api-evangelist/clio/refs/heads/main/graphql/clio-graphql.md

## Other Clio APIs (12)

- [Clio Webhooks](https://apis.io/apis/clio/webhooks/)
- [Clio App Directory](https://apis.io/apis/clio/app-directory/)
- [Clio Activities API](https://apis.io/apis/clio/clio-activities-api/)
- [Clio Activity Descriptions API](https://apis.io/apis/clio/clio-activity-descriptions-api/)
- [Clio Activity Rates API](https://apis.io/apis/clio/clio-activity-rates-api/)
- [Clio Allocations API](https://apis.io/apis/clio/clio-allocations-api/)
- [Clio Bank Accounts API](https://apis.io/apis/clio/clio-bank-accounts-api/)
- [Clio Bank Transactions API](https://apis.io/apis/clio/clio-bank-transactions-api/)
- [Clio Bank Transfers API](https://apis.io/apis/clio/clio-bank-transfers-api/)
- [Clio Bill Themes API](https://apis.io/apis/clio/clio-bill-themes-api/)
- [Clio Billable Clients API](https://apis.io/apis/clio/clio-billable-clients-api/)
- [Clio Billable Matters API](https://apis.io/apis/clio/clio-billable-matters-api/)

## Tags

Matters

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/clio/clio-matters-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/clio/.