Clio API - What is the correct format to Update (PATCH) a custom field value for a matter

Question

Anyone been able to successfully update the custom_field_values for a matter via Clio's API?

I'm trying to update the value for custom_field_values under a single matter. I'm able to send a JSON string using PATCH and update the default values for a matter like location or description using the following format

{"data":{"location":"Orange"}}

But when it comes to updating a "custom field value" I'm getting a 422 Unprocessable Entity error. I'm following Clio's v4 API Documentation and my understanding is that to update a custom_field_value you need the following JSON:

{"data":{"custom_field_values":[{"id":658213,"custom_field":{"id":139385},"value":"New Value Goes Here!"}]}}

However here is the message coming with the 422 error:

{"error":{"type":"ArgumentError","message":"An invalid argument was supplied: invalid custom field value id provided, acceptable format is <type>-<unique id>"}}

I can't interpret the part suggesting the acceptable format!

I've also tried sending the JSON in the following format which is closest to Clio's V2 API Docs for updating a custom field:

{"data":{"custom_field_values":[{"custom_field":{"id":139385},"value":"New value goes here"}]}}

But then this is what I get back:

{"error":{"type":"ArgumentError","message":"An invalid argument was supplied: custom field value for custom field 139385 already exists"}}

Please note that this is being tested in POSTMAN regardless of my development environment. I appreciate your response!

score 3 · Accepted Answer · answered Apr 23 '18 at 15:17

I've successfully created queries to update custom field values in matters many times, and these run all the time for me. I've compared your json to some examples of the json I'm successfully sending. Your syntax appears correct, but there's enough missing for me to only guess at where your mistake might be.

First, you're sending a PATCH to https://app.clio.com/api/v4/matters/{matter id}.json right? It took me a while to learn that you can't update the value of a matter's custom field with a query to https://app.clio.com/api/v4/custom_fields/{id}.json.

Second, just to clarify, the 658213 id you used above (the first id field) should be the unique id of this instance of your custom field. You won't get this until you've created an instance of the custom field particular to this matter. The second id field, where you've put 139385 is the id for the custom field itself, which you could get with a query to https://app.clio.com/api/v4/custom_fields.json.

If you're looking in the V.4 docs under Custom Fields, you won't find this, or at least I didn't. BUT you can find it in the intro section to the Matters portion fo the documentation: https://app.clio.com/api/v4/documentation#tag/Matters

Hope this helps. I'd imagine someone at Clio could help by verifying your error string is delivered when you have an incorrect custom field value unique id.

I'll also note that, from what I've seen, the unique ids of instances of custom fields attached to matters are often strings. I just sent a GET to a matter for a custom field that's a text line, and the ID came back as "text_line-*******" where the asterisks are numbers. Custom ID fields for Contact-type custom fields appear to have ids that are strings that begin with "contact-", and Custom field Instance IDS for date-type custom fields are strings that begin with "date-". If this is universal, it suggests that the `658213` id you are using is not correct. — Jacob Small, Apr 23 '18 at 15:44
Thanks Jacob. That was indeed the problem. The documentation for API V4 states that we need to send in the id for "custom field instance" as an integer (id only). However, the API does reply requesting the format to be . Which is exactly what you said for example "text_line-12345678" — Patrick Sharooz, Apr 24 '18 at 22:15

score 3 · Answer 2 · edited Aug 01 '23 at 00:07

To further clarify Jacob's answer for everyone else:

custom_field{id} is the id given to a custom_field when it's created and will be the same for all matters or contacts it's used in.

custom_field_value{id} is the id given to an instance of the custom_field added to a particular matter and unique only to that matter. The format of the value id includes the data type of the field and a unique ID 64-bit integer.
Examples: text_line-123456789, picklist-2345678901, date-3456789012, checkbox-4567890123

Important Note: Even if a value hasn't been set or isn't visible from the web GUI, the field value id can still be set. If the custom field value is set, you will need to use the update payload schema. You can verify if there if an id using a GET request to the relevant contacts or matters endpoint:

{regional_url}/api/v4/contacts/{id}.json?fields=custom_field_values{id,custom_field}

If the results include custom_field{id} is included in the results, it will have a custom_field_value{id} associated with it and you will need to use the update payload schema.

Example Payloads

To ADD a Custom Field for the first time:

    {
      "data": {
        "custom_field_values": [{
          "custom_field": {
            "id": 123456
          },
          "value": "string or integer depending on the type of CF"
        }]
      }
    }

To UPPDATE a custom field with an existing custom_field_value ID:

    {
      "data": {
        "custom_field_values": [{
          "id": "text_line-1234567",
          "custom_field": {
            "id": 123456
          },
          "value": "string or integer depending on the type of CF"
        }]
      }
    }

To DELETE an existing custom field and associated value:

    {
      "data": {
        "custom_field_values": [{
          "id": "text_line-1234567",
          "custom_field": {
            "id": 123456
          },
          "_destroy": true
        }]
      }
    }

You can combine deleting an existing value and adding in a new value in the same request which has a similar behavior to updating an existing value, but has been seen to by the community to succeed more often.

Deleting and Adding: