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) ## 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}, } ], } } ```