Work with Clio Manage matters and custom fields via the API while respecting its per-resource OAuth read/write scopes

Steps

1. Register an OAuth application in Clio and request only the specific access permissions (scopes) needed per resource - each permission is offered as separate read-only or read/write options.
2. Complete the Authorization Code grant flow; note that once a user authorizes your app, the granted scopes are fixed for that authorization even across token refreshes, so adding new requested permissions later requires the user to reauthorize.
3. Fetch matters via GET /api/v4/matters.json using the fields parameter to select nested attributes (e.g., fields=id,description,client{name}) to reduce payload size - only one level of nesting is supported, and a second-level nested field request returns 400 Bad Request.
4. When reading or updating a matter/contact's custom field, note that the custom_field_value ID embedded in the matter/contact response is a different identifier than the custom_field ID used to query the Custom Fields endpoint directly.
5. PATCH a specific custom field's value by submitting the custom_field_values array referencing the field's custom_field_id and the new value on the matter/contact update endpoint.
6. Account for the fact that deleted custom fields can still appear in API responses wherever a historical value was already stored on a record, so sync logic must tolerate stale custom_field references.