Clio API Documentation (v4)

• 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.
• For business and partnership inquiries, contact our API Partnerships team at api.partnerships@clio.com.
• For best practices and tips from the Clio development community, join the conversation in the Clio Developer Slack Channel.

A community-driven Clio Developers Stack Overflow Group also exists where you can connect and ask questions from other Clio API users.

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).

Likewise, the developer portal is available at region-specific links for the Australia, Canada, EU, and US regions.

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.

To start building on the Clio API, you’ll need a Clio account – you can review our Developer Handbook and follow the steps to sign up for an account.

Once you have an account, you can create a developer application from the Developer Portal and start building!

See our Authorization documentation →

See our Permissions documentation →

See our Fields documentation →

See our Rate Limits documentation →

See our Pagination documentation →

See our ETags documentation →

API 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.

An X-API-VERSION will be included in all successful responses, with the value being set to the API version used.

You can find our API Versioning Policy and Guidelines in our documentation hub.

The API Changelog explains each version's changes in further detail.

• 4.0.4

  Update quantity field to return values in seconds rather than hours for Activities

• 4.0.5

  • Remove matter_balances field from Bills
  • Standardize status/state enum values
  • Add a Document association to completed DocumentAutomations
  • Add rate visibility handling for Activity's price and total

• 4.0.6

  Remove document_versions collection field from Documents

• 4.0.7

  Change secure link format

• 4.0.8

  • Activity hours are redacted in the response based on the activity hours visibility setting for the user
  • Add quantity_redacted field to activities

• 4.0.9

  This is the default version

  Contacts are filtered and redacted in the response based on the new 'Contacts Visibility' user permission setting.

• 4.0.10

  Fixed validation of type query parameter when querying Notes

In Clio, applications can create custom actions in our interface. Links are unique across an application, user, location in the UI (ui_reference) and label. When the user clicks on a custom action, Clio will open a new browser tab at the target_url.

Clio will add a few URL parameters to the target_url, including the custom action ID, the ID of the user who clicked the link and the URL of the object(s) which the link was clicked on. The third party application must then look up the relevant OAuth token associated with the user and custom action, and make an authenticated request to the subject_url. This request both lets you validate the request was made by who you expected, that they have access to the record and lets you pull down any extra information you may need.

Currently supported for: Activities, Contacts, Documents and Matters

Confirming a User's Action

As custom actions require an unauthorized GET request, which can be faked, Clio has provided a way to validate that a user has actually performed an action.

When a request is sent to the URL specified on the custom action, we will include a custom_action_nonce parameter. If you send us back the custom_action_nonce in your next request to the API, Clio will use it to validate that the user who clicked the custom action matches your oauth token request. If no match is made, an error will be returned.

Webhooks are a way of detecting events in Clio without the need for polling.

A webhook can be subscribed to a number of events on a model. Some events will be different depending on the chosen model, but (with one exception) all models support the following events:

• created
• updated
• deleted

To subscribe to any or all events for a model, create a webhook record with the URL that you want webhooks to be sent to, a model, and the list of events you care about. Whenever an event happens on that model in Clio that the user is authorized to see, an HTTP request will be made to the supplied URL with details about the event. A webhook will automatically expire after a set period of time. If no expires_at parameter is provided, the webhook will expire after 3 days. The maximum duration you can set a webhook to expire after is 31 days. If you require longer than that, you can manually extend it by updating the expires_at field.

Your application needs to have the corresponding model OAuth scope when creating or updating a webhook. For example, when creating/updating a folder webhook you need the document Oauth Scope and the webhook Oauth Scope. The list of models supported by webhooks with their corresponding string identifier and ID is presented in the following table:

Please note that all webhooks MUST be using a url with the https scheme. All other schemes, including http, will be rejected.

When a webhook is sent, the payload will not include the entire object for the record. To select specific fields from the record, you can use the fields parameter when creating the webhook. For example: when creating a webhook listening for new Activity records being created, you can pass the value “id,etag,quantity,price” into the fields parameter. When an Activity is created, the id, etag, quantity, and price fields of the new Activity will be included in the webhook's payload.

For update webhooks, the fields parameter is also used to specify fields that will be “watched” by the webhook. Clio will only send a webhook when at least one of the selected fields has changed on a record.

An important note If you have never received a webhook for an object before, you will receive a webhook for that object if any fields have changed on that object, including fields you haven't subscribed to. For example: if you create a webhook that subscribes to updates to Activities and provide "price" as the field parameter value, the first time an Activity is updated after the Webhook is live will trigger a webhook event – even if the price hasn't changed. Subsequent webhook events for that Activity will only be sent when the price field changes.

Note that there is a hard limit to the size of the fields parameter. Any request containing a fields size over 1000 characters will be rejected.

Tip: Use the minimum set of fields to reduce how frequently your endpoint is hit.

As mentioned previously, almost all models support the created, updated, and deleted events. Some models also support events specific to their life cycle.

Clio Payments payments

• created is fired whenever a payment is created
• updated is fired whenever a payment is updated

All other Models

• created is fired whenever a model is created
• updated is fired whenever a model is updated
• deleted is fired whenever a model is deleted

Matters

• matter_opened is fired whenever a matter's status changes to "Open"
• matter_pended is fired whenever a matter's status changes to "Pending"
• matter_closed is fired whenever a matter's status changes to "Close"

More model-specific events will be coming soon.

A response status code of 2xx, 3xx, or 410 GONE indicate that the action was successfully processed. When a 410 GONE response is received, the webhook subscription will be disabled. All other responses will be considered unsuccessful, and they will be retried using an exponential backoff strategy.

Timeouts

Clio will wait a short period of time before the request will timeout. We will consider it an unsuccessful response and retry using an exponential backoff strategy. It is important to respond quickly. Failure to do so repeatedly may result in your webhook being disabled. If you need to do lengthy processing with the webhook, it is recommended that you defer the processing until after you have sent a response back to Clio.

Identity Confirmation

To ensure that a URL actually intends to receive webhooks from Clio, and to ensure that the payloads are actually from Clio, we will share a secret in the initial handshake.

A POST request will be made immediately after a webhook is setup, or whenever the URL changes. This request will have a unique secret in a X-Hook-Secret header along with the id of the webhook that was just created. There are two ways of confirming the webhook using this secret:

Option 1: Immediate

Upon initially receiving this secret, the endpoint can return a 200 OK response and include the same secret in a X-Hook-Secret header.

Option 2: Delayed

After receiving the secret, make a PUT request to /api/v4/webhooks/:webhook_id/activate with the secret in a X-Hook-Secret header.

Note that a webhook will not be enabled until this handshake is successful.

Confirming Hook Legitimacy

To prove that Clio is sending all subsequent messages, Clio will sign all of the requests.

Clio will compute an HMAC-SHA256 signature based on the shared secret and the request body. That signature will then be placed in a X-Hook-Signature header. The endpoint can then verify the signature to know if the message is authentic. Verification is as simple as computing an HMAC-SHA256 signature using the shared secret as the key and the request body as the message, and comparing it to the X-Hook-Signature header.

A Webhook can be created for the Activities model, to trigger on any events and return the id and etag fields:

  {
    "data":{
      "url":"https://my/callback/url",
      "fields":"id,etag",
      "model":"activity",
      "events":["created","deleted","updated"]
    }
  }

This webhook would have the following responses for different actions. It would trigger on any events for the model, and return the id and etag fields for that model, and the event type.

Notes:

• The model field accepts both the string identifier of the model as in the example, or its ID. In the latter case, you would have provided the ID parameter: "model":2. Refer to the table listing the models supported by webhooks for matching the model name with its ID.

Create

In the event of an Activity being created, your URL would receive the following JSON:

  {
    "data":{
      "id":152,
      "etag":"\"9a103be2201ae758992733a91f02903f\""
    },
    "meta":{
      "event":"created",
      "webhook_id":1234
    }
  }

Update

In the event of an Activity being updated, your URL would receive the following JSON:

  {
    "data":{
      "id":152,
      "etag":"\"9d9ef9fb42a505976d90d564c1596f11\""
    },
    "meta":{
      "event":"updated",
      "webhook_id":1234
    }
  }

Delete

In the event of an Activity being deleted, your URL would receive the following JSON:

  {
    "data":{
      "id":152,
      "etag":"\"3cc31bfbd6cfc16d3d7123423e437079\""
    },
    "meta":{
      "event":"deleted",
      "webhook_id":1234
    }
  }

Activities (Time Entries and Expense Entries) track work done at a firm. Activities are recorded in Clio and then posted on bills to clients.

Time Entries can be either be hourly-billable or flat-rate. An hourly-billable Time Entry is valued at the billing rate multiplied by the time entered. Examples could be a phone call, or a research session. A flat-rate Time Entry has a set value. Examples could be a visa application, or a contract review.

Expenses are reimbursable costs the firm pays on behalf of a client (for example, postage, copy fees, etc.).

Support Link

Activities in Clio