Custom Actions

Third-party applications in Clio have the ability to create custom actions within the Clio Manage interface. Custom actions enable Clio Manage users to launch cross-application workflows from within Clio Manage, reducing the time it takes to switch between applications. Custom actions appear as dropdown menu options on Activies, Contacts, Documents, Folders, or Matters. When a user selects the custom action, they are sent to a URL specified by the integration partner.

This guide is intended to help integration partners understand how custom actions work and how to create them.

Creating a Custom Action

Access Permissions

Creating Custom actions requires the custom_actions access permission. If you're not sure whether your application has this scope, check your application settings in the Developer Portal.

Custom actions are created by making a POST request to the /api/v4/custom_actions endpoint. The request must include the following parameters:

Parameter	Type	Description
label	String	The label that will be displayed to users in the Clio Manage interface.
target_url	String	The URL that will be opened when a user clicks the custom action. See "Receiving a Custom Action" for more information about how this parameter works.
ui_reference	String	The location in the Clio Manage interface where the custom action will appear. See "Where can Custom Actions appear?" for more information.

The full API reference for the custom actions endpoint can be found in our API Reference page

A sample request body is shown below:

{
  "data": {
    "label": "My Custom Action",
    "target_url": "https://myapp.com/custom-action",
    "ui_reference": "matters/show"
  }
}

Custom actions are scoped to an individual user. If your integration is used by multiple users within a single firm, you must create a custom action using each user's access token.

Receiving a Custom Action

When a user clicks on a custom action, Clio Manage will open a new browser tab pointing to the target URL. Several URL parameters will be added to the target URL:

Parameter	Description
custom_action_id	The ID of the custom action that was clicked.
user_id	The ID of the user who clicked the custom action.
subject_url	The URL of the record on which the custom action was clicked, sent as a URL-encoded relative URL for the record in the API (e.g. %2Fapi%2Fv4%2Fmatters%2F1234567)
custom_action_nonce	A single-use code used to verify that the call originated from Clio. See "Confirming a User's Action" for more information.

A sample request URL is shown below:

https://myapp.com/custom-action?custom_action_id=1&user_id=9999999&subject_url=%2Fapi%2Fv4%2Fmatters%2F1234567&custom_action_nonce=100...7d43

Confirming a User's Action

Because custom actions require an unauthorized GET request made from a user's browser, it's important to validate that a user has actually performed an action within Clio.

When a request is sent to the URL specified on the custom action, Clio includes a unique custom_action_nonce parameter. If you send the custom_action_nonce in your next request to the API as a query parameter, Clio will use it to validate that the user who clicked the custom action matches your oauth token request. If the nonce does not match, a 403 Forbidden error will be returned.

The nonce value is a single-use code and has an expiry of 60 seconds.

Where can Custom Actions appear?

Custom actions are currently supported for Activities, Contacts, Documents, Folders, and Matters. Depending on which of these objects you work with, the custom action will appear only in the locations outlined below.

Activities, Contacts, and Matters – Table View

Custom actions are shown when selecting the dropdown menu beside the Edit button for each individual Activity, Contact, or Matter.

Activities, Contacts, and Matters – Singular View

When viewing the details of a single Activity, Contact, or Matter, custom actions under the More Actions dropdown in the header.

Documents and Folders - Table View

Custom actions are shown when selecting the dropdown menu beside the View button for each individual Document or Folder.

Documents – Singular View

In the case of Documents, custom actions can be found in the dropdown beside the Download for each document.