Clio Matter Contacts API

All clients, prospective clients, companies, and external co-counsels can be viewed as Contacts under the Contacts tab in Clio Manage.[Support Link](https://help.clio.com/hc/en-us/articles/9290486281627-Clio-Manage-Contacts-Overview)## Contact NameWhen creating a contact of type "Person" you must provide at least a first name or a last name. This can be done in one of two ways:1. Providing the name components explicitly (preferred): Using the `first_name` and `last_name` parameters.2. Providing the full name (discouraged): Using the `name` parameter, you can provide the person's full name (e.g. "John Smith") and Clio will attempt to infer the individual components of the name. If it is unable to do so, you will receive a "422 Unprocessable Entity: At least one of first name or last name must be provided" Error.**We recommend using the individual name fields when possible to avoid any ambiguities.**## AssociationsA Contact can be persisted with its associations in a single request. The followings detail the nested attributes to persist the associations.### AddressesCheckout the sample request to update the Addresses of a Contact:```jsonRequest PATCH /api/v4/contacts/1.json { data: { addresses: [ // update { id: 1, name: "Work", country: "Canada" }, // create { name: "Home", street: "1234 Main Street", city: "Burnaby", province: "BC", country: "Canada",postal_code: "V1A 1A1" }, // destroy { id: 2, _destroy: true } ] }```### Custom Field ValuesA CustomFieldValue contains the value of a CustomField for a Contact.Below are some examples of how to create, read, update, and destroy the CustomFieldValues of a Contact:#### 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/contacts/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 Contact, e.g.: `/api/v4/contacts/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/contacts/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 Contact, e.g.: `/api/v4/contacts/1?fields=id,name,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/contacts/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 Contact, e.g.: `/api/v4/contacts/1?fields=id,name,custom_field_values{id,value}````jsonRequest PATCH /api/v4/contacts/1.json { data: { custom_field_values: [ { id: "picklist-2", _destroy: true } ] } }```### Email AddressesCheckout the sample request to update the Email Addresses of a Contact:```jsonRequest PATCH /api/v4/contacts/1.json { data: { email_addresses: [ // update { id: 1, name: "Work", address: "demo@clio.com" }, // create { name: "Home", address: "home@clio.com" }, // destroy { id: 2, _destroy: true } ] }```### Instant MessengersCheckout the sample request to update the Instant Messengers of a Contact:```jsonRequest PATCH /api/v4/contacts/1.json { data: { instant_messengers: [ // update { id: 1, name: "Work", address: "https://twitter.com/goclio" }, // create { name: "Other", address: "https://www.facebook.com/GoClio/" }, // destroy { id: 2, _destroy: true } ] }```### Phone NumbersCheckout the sample request to update the Phone Numbers of a Contact:```jsonRequest PATCH /api/v4/contacts/1.json { data: { phone_numbers: [ // update { id: 1, name: "Work", number: "123-456-7890" }, // create { name: "Other", number: "000-000-0000" }, // destroy { id: 2, _destroy: true } ] }```### Web SiteCheckout the sample request to update the Web Site of a Contact:```jsonRequest PATCH /api/v4/contacts/1.json { data: { web_sites: [ // update { id: 1, name: "Work", address: "https://help.clio.com/" }, // create { name: "Other", address: "https://www.clio.com/about/careers/" }, // destroy { id: 2, _destroy: true } ] }```