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}, } ], } } ```
Documentation
Specifications
Other Resources
openapi: 3.0.0
info:
title: Clio API Documentation Activities Matters API
contact:
name: Clio API Support
email: api@clio.com
description: "# Developer Support and Feedback\n* Clio takes the availability and stability of our API seriously; please report any **degradations** or **breakages** to Clio's API Support team at [api@clio.com](mailto:api@clio.com).\n* For business and partnership inquiries, contact our API Partnerships team at [api.partnerships@clio.com](mailto:api.partnerships@clio.com).\n* For best practices and tips from the Clio development community, join the conversation in the [Clio Developer Slack Channel](https://join.slack.com/t/clio-public/shared_invite/zt-36i0eqgo1-7POORPtMJpp2N0~_auL2IQ).\n\nA community-driven [Clio Developers Stack Overflow Group](https://stackoverflow.com/questions/tagged/clio-api) also exists where you can connect and ask questions from other Clio API users.\n# Getting Started\n> **Note:** The API is available in four distinct data regions: Australia (au.app.clio.com), Canada (ca.app.clio.com), EU (eu.app.clio.com) and US (app.clio.com).\n>\n> Likewise, the developer portal is available at region-specific links for the [Australia](https://au.developers.clio.com), [Canada](https://ca.developers.clio.com), [EU](https://eu.developers.clio.com), and [US](https://developers.clio.com) regions.\n>\n> This document assumes the US region is being used (app.clio.com). If you're building in one of the other regions, you should adapt the links and examples as necessary.\n\nTo start building on the Clio API, you’ll need a Clio account – you can review our [Developer Handbook](https://docs.developers.clio.com/) and follow the steps to sign up for an account.\n\nOnce you have an account, you can [create a developer application](https://docs.developers.clio.com/api-docs/applications) from the [Developer Portal](https://developers.clio.com) and start building!\n# Authorization with OAuth 2.0\nSee our [Authorization documentation →](https://docs.developers.clio.com/api-docs/authorization)\n# Permissions\nSee our [Permissions documentation →](https://docs.developers.clio.com/api-docs/permissions)\n# Fields\nSee our [Fields documentation →](https://docs.developers.clio.com/api-docs/fields)\n# Rate Limiting\nSee our [Rate Limits documentation →](https://docs.developers.clio.com/api-docs/rate-limits)\n# Paging\nSee our [Pagination documentation →](https://docs.developers.clio.com/api-docs/paging)\n# ETags\nSee our [ETags documentation →](https://docs.developers.clio.com/api-docs/etags)\n# Minor Versions\nAPI v4 supports multiple minor versions. Versions are of the form '4.X.Y'. To request a specific version, you can use an `X-API-VERSION` header in your request, with the header value set to the API version you're requesting. If this header is omitted, it will be treated as a request for the default API version. If the header is present but invalid, it will return a `410 Gone` response. If the header is present and valid, but it is no longer supported, it will return a `410 Gone` response.\n\nAn `X-API-VERSION` will be included in all successful responses, with the value being set to the API version used.\n\nYou can find our [API Versioning Policy and Guidelines](https://docs.developers.clio.com/api-docs/api-versioning-policy) in our documentation hub.\n\nThe [API Changelog](https://docs.developers.clio.com/api-docs/api-changelog) explains each version's changes in further detail.\n### [4.0.4](https://docs.developers.clio.com/api-docs/api-changelog#404)\n\n * Update `quantity` field to return values in seconds rather than hours for Activities\n\n### [4.0.5](https://docs.developers.clio.com/api-docs/api-changelog#405)\n\n * Remove `matter_balances` field from Bills\n* Standardize status/state enum values\n* Add a Document association to completed DocumentAutomations\n* Add rate visibility handling for Activity's price and total\n\n### [4.0.6](https://docs.developers.clio.com/api-docs/api-changelog#406)\n\n * Remove `document_versions` collection field from Documents\n\n### [4.0.7](https://docs.developers.clio.com/api-docs/api-changelog#407)\n\n * Change secure link format\n\n### [4.0.8](https://docs.developers.clio.com/api-docs/api-changelog#408)\n\n * `Activity` hours are redacted in the response based on the activity hours visibility setting for the user\n * Add `quantity_redacted` field to activities\n\n### [4.0.9](https://docs.developers.clio.com/api-docs/api-changelog#409)\n\n * Contacts are filtered and redacted in the response based on the new 'Contacts Visibility' user permission setting.\n\n### [4.0.10](https://docs.developers.clio.com/api-docs/api-changelog#4010)\n\n * Fixed validation of `type` query parameter when querying Notes\n\n### [4.0.12](https://docs.developers.clio.com/api-docs/api-changelog#4012)\n\n * Restrict fields for CalendarEntry that should only be visible to event owners, editors, and viewers\n\n### [4.0.13](https://docs.developers.clio.com/api-docs/api-changelog#4013)\n\n **This is the default version**\n\n * Add association limits to Contacts\n* Returns 422 Unprocessable Entity when association limits are exceeded\n\n\n"
version: v4
x-logo:
url: https://www.clio.com/wp-content/uploads/2015/05/Container-5-Logo.png
servers:
- url: https://app.clio.com/api/v4
description: US region Production Server
- url: https://eu.app.clio.com/api/v4
description: Europe region Production Server
- url: https://ca.app.clio.com/api/v4
description: Canada region Production Server
- url: https://au.app.clio.com/api/v4
description: Australia region Production Server
tags:
- name: Matters
description: "[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.\n\n[Support Link](https://help.clio.com/hc/en-us/articles/9285920226075-Clio-Manage-Matters-Overview)\n\n[Matters in Clio](http://app.clio.com/matters)\n\n## Associations\nA Matter can be persisted with its associations in a single request. The followings detail the nested attributes to persist the associations.\n\n### Custom Field Values\nA CustomFieldValue contains the value of a CustomField for a Matter.\nBelow are some examples of how to create, read, update, and destroy the CustomFieldValues of a Matter:\n#### Create\nNote: 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).\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n custom_field_values: [\n { custom_field: { id: 2 }, value: \"Initial value\" }\n ]\n }\n }\n```\n#### Read\nNote: The `id` of the CustomFieldValue is a composite value including the custom field type. Use this `id` to update and destroy the CustomFieldValue.\nThe `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}`\n\nNote: The `id` may be `NULL` when the CustomField is displayed by default but has not yet been given a value.\n```json\nRequest\n GET /api/v4/matters/1.json?fields=custom_field_values{id,value,custom_field}\n {\n data: {\n custom_field_values: [\n {\n id: \"text_line-1\",\n value: \"Current value\",\n custom_field: { id: 2 }\n }\n ]\n }\n }\n```\n#### Update\nNote: 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}`\n\nNote: If the `id` is `NULL`, you must provide `custom_field{id}` to create the CustomFieldValue and assign a value (see **Create**).\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n custom_field_values: [\n { id: \"text_line-1\", value: \"Updated value\" }\n ]\n }\n }\n```\n#### Destroy\nNote: 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}`\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n custom_field_values: [\n { id: \"picklist-2\", _destroy: true }\n ]\n }\n }\n```\n\n### Custom Rates\nEach Matter can be set up to be billed on an Hourly basis, Flat Fee basis, or on Contingency.\nTo set the rate type, assign `custom_rate[type]` with one of the values, `\"HourlyRate\"`, `\"FlatRate\"` or `\"ContingencyFee\"`.\nBy default, a Matter is billed on an hourly basis. If the rate type is modified, the persisted rates will be deleted.\n\n[Support Link](https://help.clio.com/hc/en-us/articles/9289801180187)\n\n#### Hourly Rates\nSelecting the `\"HourlyRate\"` type will record time entries based on the custom hourly rates.\nA custom hourly rate can be associated to a User or a Group.\nCheckout the sample request to update the hourly rates of a Matter:\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n custom_rate: {\n type: \"HourlyRate\",\n rates: [\n // update a rate for a user\n { id: 1, rate: 100, user: { id: 1 } },\n // update a rate for a group\n { id: 2, rate: 100, group: { id: 1 } },\n // create a rate for a user\n { rate: 100, user: { id: 2 } },\n // create a rate for a group\n { rate: 100, group: { id: 2 } },\n // destroy a rate\n { id: 3, _destroy: true }\n ]\n }\n }\n }\n```\n\n#### Flat Rate\nSelecting the `\"FlatRate\"` type will bill the matter with a flat fee. A Matter can only have one flat rate.\nFor associated objects, you can specify `_destroy` attribute to delete the rate.\n\nCheckout the sample request to update the flat rate of a Matter:\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n custom_rate: {\n type: \"FlatRate\",\n rates: [\n {\n id: 1,\n user: { id: 1 },\n activity_description: { id: 1 },\n rate: 100,\n }\n ]\n }\n }\n }\n```\n\n#### Contingency Fee\nSelecting 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.\nA Matter can only have one definition of contingency fee.\nFor associated objects, you can specify `_destroy` attribute to delete the rate.\n\nContingency Fee Matters are not available to all plan types. See [here](https://www.clio.com/pricing/) for feature support across different plans.\n\nCheckout the sample request to update the contingency fee of a Matter:\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n custom_rate: {\n type: \"ContingencyFee\",\n rates: [\n {\n id: 1,\n user: { id: 1 },\n rate: 20,\n }\n ]\n }\n }\n }\n```\n### Matter Budget\nClio supports tracking a matter budget directly within a Matter.\nA Matter can only have one matter budget associated with it.\nA matter budget can not be added to flat rate matters.\nFor associated objects, you can specify the `_destroy` attribute to delete the Matter Budget.\n\nMatter Budget are not available to all plan types. See [here](https://www.clio.com/pricing/) for feature support across different plans.\n\nCheck out the sample request to update the matter budget of a Matter:\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n matter_budget: {\n budget: 5000000,\n include_expenses: true,\n notification_threshold: 100,\n notify_users: true\n users: [\n { id: 1 },\n // destroy\n { id: 2, _destroy: true }\n ]\n }\n }\n }\n```\n### Grant Matter\nClio supports associating a Grant with a Matter, using Grant Matters.\nA Matter can have up to three Grants (and Grant Matters) associated with it.\nFor associated objects, you can specify the `_destroy` attribute to delete Grant Matters.\n\nGrant Matters are only for legal aid US customers\n\nCheckout the sample request to update a Grant Matter:\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n \"grant_matters\": [\n {\"id\":{{existing_grant_matter_id}}}\n ]\n }\n }\n ```\n### Relationships\nThere 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.\n\n#### 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.\n\nCheckout the sample request to update Relationships of a Matter:\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n relationships: [\n // update\n { id: 1, contact: { id: 1 }, description: \"Opposing Counsel\" },\n // create\n { contact: { id: 2 }, description: \"Judge\" },\n // destroy\n { id: 2, _destroy: true }\n ]\n }\n }\n```\n\n### Statue Of Limitations\nClio supports to track a Statute of Limitations date directly within a Matter.\nIt can be associated with reminders as a Task.\nA Matter can only have one definition of Statue of Limitations.\nFor associated objects, you can specify `_destroy` attribute to delete the Statue of Limitations.\n\nCheck out the sample request to update the Statue of Limitations and its reminders of a Matter:\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n statue_of_limitations: [\n due_at: \"20201231\",\n status: \"open\",\n reminders: [\n // update\n { id: 1, duration_unit: \"days\", duration_value: 1, notification_method: { id: 1 } },\n // create\n { duration_unit: \"days\", duration_value: 1, notification_method: { id: 2 } },\n // destroy\n { id: 2, _destroy: true }\n ]\n ]\n }\n }\n```\n\n### Task Template Lists\nClio supports assigning task template lists to a matter from with the same request that\ncreates or updates a matter. Please note that a task template list **can only be\nassigned**. Once a task template list is assigned, it **cannot be modified or destroyed**.\n\nCheckout the sample request to assign a task template list id to a matter:\n\n```json\nRequest\n PATCH /api/v4/matters/1.json\n {\n data: {\n task_template_list_instances: [\n {\n notify_assignees: true,\n task_template_list: {id: 1},\n },\n {\n notify_assignees: false,\n task_template_list: {id: 2},\n }\n ],\n }\n }\n```\n"
paths:
/matters.json:
get:
tags:
- Matters
summary: Return the data for all Matters
operationId: Matter#index
description: Outlines the parameters, optional and required, used when requesting the data for all Matters
parameters:
- name: X-API-VERSION
in: header
description: 'The [API minor version](#section/Minor-Versions). Default: latest version.'
required: false
schema:
type: string
- name: billable
in: query
description: Filter Matter records to those which are billable.
required: false
schema:
type: boolean
- name: client_id
in: query
description: The unique identifier for a single Contact. The keyword `null` is not valid for this field. The list will be filtered to include only the Matter records with the matching property.
required: false
schema:
type: integer
format: int64
- name: close_date[]
in: query
description: 'Filter Matter records by the close date. The date should be provided in the format YYYY-MM-DD.
e.g. `?close_date==2020-01-01`, `?close_date=<=2021-12-31`
You can provide more than one value to narrow the results of this filter. You can do so by passing several individual values and appending `[]` to the parameter name.
e.g. `?close_date[]=>=2020-01-01&close_date[]=<=2021-12-31`
Note that, when providing multiple values for this filter, only Matter records that meet *all* filter conditions will be returned.
'
required: false
schema:
type: string
enum:
- '>DATE'
- '>=DATE'
- =DATE
- <=DATE
- <DATE
- name: created_since
in: query
description: Filter Matter records to those having the `created_at` field after a specific time. (Expects an ISO-8601 timestamp).
required: false
schema:
type: string
format: date-time
- name: currency_id
in: query
description: Filter Matter records to those of a specific currency.
required: false
schema:
type: integer
format: int64
- name: custom_field_ids[]
in: query
description: Filter Matter's custom_field_values to only include values for the given custom field unique identifiers.
required: false
schema:
type: integer
format: int64
- name: custom_field_values
in: query
description: 'Filter records to only those with the given custom field(s) set. The value is compared using the operator provided, or,
if the value type only supports one operator, the supported operator is used. In the latter case, no check for operator is performed on the input string.
The key for the custom field value filter is the custom_field.id. e.g. `custom_field_values[12345]`
If an operator is used for a type that does not support it, an `400 Bad Request` is returned.
*Supported operators:*
* `checkbox`, `contact`, `matter`, `picklist` : `=`
e.g. `?custom_field_values[1]=42`
* `currency`, `date`, `time`, `numeric` : `=`, `<`, `>`, `<=`, `>=`
e.g. `?custom_field_values[1]=>=105.4`
* `email`, `text_area`, `text_line`, `url` : `=`
e.g. `?custom_field_values[1]=url_encoded`
*Multiple conditions for the same custom field:*
If you want to use more than one operator to filter a custom field, you can do so by passing in an array of values.
e.g. `?custom_field_values[1]=[<=50, >=45]`
'
required: false
schema:
type: string
enum:
- '='
- <
- '>'
- <=
- '>='
- name: fields
in: query
description: The fields to be returned. See response samples for what fields are available. For more information see the [fields section](#section/Fields).
required: false
schema:
type: string
- name: grant_id
in: query
description: The unique identifier for a single Grant. Use the keyword `null` to match those without a Matter. The list will be filtered to include only the Matter records with the matching property.
required: false
schema:
type: integer
format: int64
- name: group_id
in: query
description: The unique identifier for a single Group. The keyword `null` is not valid for this field. The list will be filtered to include only the Matter records with the matching property.
required: false
schema:
type: integer
format: int64
- name: ids[]
in: query
description: Filter Matter records to those having the specified unique identifiers.
required: false
schema:
type: integer
format: int64
- name: limit
in: query
description: 'A limit on the number of Matter records to be returned. Limit can range between 1 and 200. Default: `200`.'
required: false
schema:
type: integer
format: int32
- name: notification_event_subscriber_user_id
in: query
description: The unique identifier for a single NotificationEventSubscriber. Use the keyword `null` to match those without a Matter. The list will be filtered to include only the Matter records with the matching property.
required: false
schema:
type: integer
format: int64
- name: open_date[]
in: query
description: 'Filter Matter records by the open date. The date should be provided in the format YYYY-MM-DD.
e.g. `?open_date==2020-01-01`, `?open_date=<=2021-12-31`
You can provide more than one value to narrow the results of this filter. You can do so by passing several individual values and appending `[]` to the parameter name.
e.g. `?open_date[]=>=2020-01-01&open_date[]=<=2021-12-31`
Note that, when providing multiple values for this filter, only Matter records that meet *all* filter conditions will be returned.
'
required: false
schema:
type: string
enum:
- '>DATE'
- '>=DATE'
- =DATE
- <=DATE
- <DATE
- name: order
in: query
description: 'Orders the Matter records by the given field. Default: `id(asc)`.'
required: false
schema:
type: string
enum:
- display_number(asc)
- display_number(desc)
- custom_number(asc)
- custom_number(desc)
- id(asc)
- id(desc)
- client.name(asc)
- client.name(desc)
- clients(asc)
- clients(desc)
- open_date(asc)
- open_date(desc)
- practice_area.name(asc)
- practice_area.name(desc)
- matter_stage.name(asc)
- matter_stage.name(desc)
- responsible_attorney.name(asc)
- responsible_attorney.name(desc)
- close_date(asc)
- close_date(desc)
- pending_date(asc)
- pending_date(desc)
- updated_at(asc)
- updated_at(desc)
- created_at(asc)
- created_at(desc)
- statute_of_limitations.due_at(asc)
- statute_of_limitations.due_at(desc)
- originating_attorney.name(asc)
- originating_attorney.name(desc)
- grants(asc)
- grants(desc)
- matter_stage_updated_at(asc)
- matter_stage_updated_at(desc)
- name: originating_attorney_id
in: query
description: The unique identifier for a single User. Use the keyword `null` to match those without a Matter. The list will be filtered to include only the Matter records with the matching property.
required: false
schema:
type: integer
format: int64
- name: page_token
in: query
description: A token specifying which page to return.
required: false
schema:
type: string
- name: pending_date[]
in: query
description: 'Filter Matter records by the pending date. The date should be provided in the format YYYY-MM-DD.
e.g. `?pending_date==2020-01-01`, `?pending_date=<=2021-12-31`
You can provide more than one value to narrow the results of this filter. You can do so by passing several individual values and appending `[]` to the parameter name.
e.g. `?pending_date[]=>=2020-01-01&pending_date[]=<=2021-12-31`
Note that, when providing multiple values for this filter, only Matter records that meet *all* filter conditions will be returned.
'
required: false
schema:
type: string
enum:
- '>DATE'
- '>=DATE'
- =DATE
- <=DATE
- <DATE
- name: practice_area_id
in: query
description: The unique identifier for a single PracticeArea. The keyword `null` is not valid for this field. The list will be filtered to include only the Matter records with the matching property.
required: false
schema:
type: integer
format: int64
- name: query
in: query
description: Wildcard search for `display_number`, `number` or `description` matching a given string, as well as the `first_name`, `last_name` or `name` of the associated client.
required: false
schema:
type: string
- name: responsible_attorney_id
in: query
description: The unique identifier for a single User. Use the keyword `null` to match those without a Matter. The list will be filtered to include only the Matter records with the matching property.
required: false
schema:
type: integer
format: int64
- name: responsible_staff_id
in: query
description: The unique identifier for a single User. Use the keyword `null` to match those without a Matter. The list will be filtered to include only the Matter records with the matching property.
required: false
schema:
type: integer
format: int64
- name: status
in: query
description: Filter Matter records to those with a given status. It accepts comma-separated statuses, e.g. `open,pending`.
required: false
schema:
type: string
enum:
- open
- closed
- pending
- name: subscriber_user_id
in: query
description: The unique identifier for a single NotificationEventSubscriber. Use the keyword `null` to match those without a Matter. The list will be filtered to include only the Matter records with the matching property.
required: false
schema:
type: integer
format: int64
- name: updated_since
in: query
description: Filter Matter records to those having the `updated_at` field after a specific time. (Expects an ISO-8601 timestamp).
required: false
schema:
type: string
format: date-time
responses:
'200':
description: Ok
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Matter_List'
'400':
description: Bad Request
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Error'
post:
tags:
- Matters
summary: Create a new Matter
operationId: Matter#create
description: Outlines the parameters and data fields used when creating a new Matter
parameters:
- name: X-API-VERSION
in: header
description: 'The [API minor version](#section/Minor-Versions). Default: latest version.'
required: false
schema:
type: string
- name: custom_field_ids[]
in: query
description: Filter Matter's custom_field_values to only include values for the given custom field unique identifiers.
required: false
schema:
type: integer
format: int64
- name: fields
in: query
description: The fields to be returned. See response samples for what fields are available. For more information see the [fields section](#section/Fields).
required: false
schema:
type: string
responses:
'201':
description: Created
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Matter_Show'
'400':
description: Bad Request
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable Entity
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/Error'
requestBody:
description: Request Body for Matters
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
properties:
billable:
type: boolean
default: true
description: Whether or not the matter is billable.
client:
type: object
properties:
id:
type: integer
format: int64
description: The unique identifier for a single Contact associated with the Matter. The keyword `null` is not valid for this field.
required:
- id
client_reference:
type: string
description: Client Reference string for external uses.
close_date:
type: string
format: date
description: Date the Matter was set to closed. (Expects an ISO-8601 date).
currency:
type: object
description: Currency of the matter
custom_field_set_associations:
type: array
items:
type: object
properties:
display_order:
type: integer
format: int32
description: The order to display the CustomFieldSet in a Matter. If not specified, it is added as the last CustomFieldSet of the Matter.
custom_field_set:
type: object
properties:
id:
type: integer
format: int64
description: The unique identifier for a single CustomFieldSet associated with the CustomFieldSetAssociation. The keyword `null` is not valid for this field.
required:
- id
required:
# --- truncated at 32 KB (208 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clio/refs/heads/main/openapi/clio-matters-api-openapi.yml