Clio Matters API

[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)## AssociationsA Matter can be persisted with its associations in a single request. The followings detail the nested attributes to persist the associations.### Custom Field ValuesA 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:#### CreateNote: 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).```jsonRequest PATCH /api/v4/matters/1.json { data: { custom_field_values: [ { custom_field: { id: 2 }, value: "Initial value" } ] } }```#### ReadNote: 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.```jsonRequest 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 } } ] } }```#### UpdateNote: 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**).```jsonRequest PATCH /api/v4/matters/1.json { data: { custom_field_values: [ { id: "text_line-1", value: "Updated value" } ] } }```#### DestroyNote: 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}````jsonRequest PATCH /api/v4/matters/1.json { data: { custom_field_values: [ { id: "picklist-2", _destroy: true } ] } }```### Custom RatesEach 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 RatesSelecting 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:```jsonRequest 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 RateSelecting 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:```jsonRequest PATCH /api/v4/matters/1.json { data: { custom_rate: { type: "FlatRate", rates: [ { id: 1, user: { id: 1 }, activity_description: { id: 1 }, rate: 100, } ] } } }```#### Contingency FeeSelecting 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:```jsonRequest PATCH /api/v4/matters/1.json { data: { custom_rate: { type: "ContingencyFee", rates: [ { id: 1, user: { id: 1 }, rate: 20, } ] } } }```### Matter BudgetClio 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:```jsonRequest 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 MatterClio 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 customersCheckout the sample request to update a Grant Matter:```jsonRequest PATCH /api/v4/matters/1.json { data: { "grant_matters": [ {"id":{{existing_grant_matter_id}}} ] } } ```### RelationshipsThere 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:```jsonRequest 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 LimitationsClio 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:```jsonRequest 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 ListsClio supports assigning task template lists to a matter from with the same request thatcreates or updates a matter. Please note that a task template list **can only beassigned**. 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:```jsonRequest 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}, } ], } }```