FirmOps.io

Clio API

The Clio API in production: what the docs leave out

Clio's API docs tell you what the endpoints are. They do not tell you which writes succeed and change nothing, which filters are ignored, or why a file you uploaded never appears. These are the things we learned writing to Clio every day for a personal injury firm.

API basics checked November 19, 2026 against Clio's developer docs. Everything else is from production. Clio changes its API; its docs and your own tests win.

Written by FirmOps, a Vertana brand. Our integration code runs Conduit Law, a personal injury firm, on Clio Manage every day: opening matters, filing letters and documents, logging costs, moving stages, posting trust disbursements and reading the file for staff and for AI. We do not sell Clio and Clio does not pay us.

Clio API basics

  • Version. Clio Manage's API is REST, version 4.
  • Auth. OAuth 2.0. A Clio user approves your app and you act with their access token, so what you can see and change follows that user's Clio permissions.
  • Regions. Clio runs separate instances for the US, Canada, EMEA and Australia. The base URL must match the account's region, and a token from one region does not work in another.
  • Rate limit. 50 requests per minute per token by default at peak, 429 when exceeded.
  • Docs. docs.developers.clio.com, with a developer portal per region for registering your app.
RegionClio Manage API base URL
United Stateshttps://app.clio.com/api/v4
Canadahttps://ca.app.clio.com/api/v4
EMEAhttps://eu.app.clio.com/api/v4
Australiahttps://au.app.clio.com/api/v4

Sources: regions, rate limits and the developer FAQ.

What the Clio API docs leave out

Each of these cost us a bug in production. Most failed silently: a 200, no error, and wrong data. That is the pattern to design for with Clio. Check the result, not the status code.

1. A document upload is three calls, and the third one is not optional

Uploading a file to a matter is: create the document record, PUT the bytes to the storage URL Clio hands back, then PATCH the document with the version uuid and fully_uploaded set to true. Clio does not finish the upload for you after the PUT.

Skip the third call and nothing errors. You get a document id back, the storage PUT returns 200, and the file never shows up in the matter. Downloading it returns 404. We shipped that bug once and only caught it because a letter went missing from a file.

Two traps on the finishing call: sending uploaded: true returns 200 and does nothing, and sending fully_uploaded without the uuid returns a 422 that names the missing uuid. Capture the uuid from latest_document_version when you create the record, and check fully_uploaded is true afterward.

2. Webhooks are a hint. Polling with updated_since is the source of truth

We built matter sync on webhooks first and it kept missing events. One matter created in Clio never reached our database for 15 days. Clio's docs also say webhooks expire after 3 days by default and 31 days at most unless you extend them, start in a pending state until the handshake completes, and get suspended after repeated delivery failures.

What works: a scheduled job that asks for records with updated_since set to a saved checkpoint, minus a few minutes of overlap so a run that dies halfway does not drop anything. Keep webhooks if you like them for speed, but treat them as supplemental.

3. The fields parameter is required in practice, and it only nests one level

Leave out fields= and most endpoints return little more than id and etag. Ask for what you need.

One level of nesting works: matter{id,display_number}, client{id,name}. Two levels returns 400 InvalidFields, and the error message is confusing: a closing brace ends up inside the field name. Custom field values with their definitions nested inside them is the common place to hit this. Fetch the values flat, fetch the custom field definitions in a second call, and join them yourself.

Field names are not uniform across resources. Notes expose author{id,name}; asking for user returns 400. Calendar entries expose calendar_owner{id,name}, not calendar{id}.

4. Clio silently ignores filters it does not know

Send an unsupported query parameter to activities and Clio returns 200 with everything, as if you had not filtered at all. billed, bill_id and matter_status on activities are all dropped this way. status=billed, unbilled or billable is the one that works.

The test we use for any filter we have not proved: set the boundary absurdly far away, like a date ten years in the future. A real filter returns zero records. An ignored one returns the same count as no filter. Then spot-check the timestamps on what comes back.

The reverse also happens: calendar entries accept from and to datetime filters that the public docs do not list. Probe, do not assume.

5. Pages stop at 200, and offset paging breaks exactly when you need it

Ask for limit=1000 and you get 200 records with no error. Every limit above 200 in a codebase is a silent truncation. We found a report showing 200 open matters when the firm had more than twice that.

Manual offset paging works on the first pages, then fails with a 422 telling you to use cursor pagination once volume grows. Follow meta.paging.next. We take the page_token out of that URL and reissue our own query with it, so our fields and filters stay ours.

On a large unfiltered query, the record count in meta saturates at 10,000. Do not use it as a firm-wide total.

6. The rate limit is per token, so call count is the only lever

Clio documents a default limit of 50 requests per minute per access token during peak hours, returns 429 Too Many Requests when you go over, and sends X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and, on a 429, Retry-After.

Because the limit is per token, running calls in parallel on one token buys nothing. We put every call through one gate. When a screen is slow, count the Clio calls on it first. The usual fix is passing along data you already have instead of re-fetching the matter, and fetching contacts in one batch by id.

Background sweeps and staff clicks share that one budget. Give interactive requests priority, with a guaranteed share for background work so it never starves. And put a timeout on every request: one Clio call that never answered held a job for over ten minutes before anything noticed.

7. Some fields accept a write and keep the old value

billing_method on a matter is derived. Send it on create or update and you get 200 with hourly still set. To make a matter contingency or flat fee, PATCH a custom_rate (type ContingencyFee or FlatRate, with a user id on each rate) after the matter exists. It cannot be set inline on create.

Tasks are completed by setting status to complete. There is no complete boolean, and completed_at is set by Clio. The allowed status values only appear in the 422 you get when you send a wrong one.

Notes written as HTML need detail_text_type set to rich_text. The default is plain text, and Clio escapes the markup on the way in, so staff see literal tags in the note.

Time entry quantity is in seconds, not hours. 3600 is one hour.

8. Deleted custom fields are still in the list, and writes to them succeed

The custom fields endpoint returns soft-deleted definitions alongside live ones, and Clio lets a firm reuse the name. So a retired field and its replacement can share a name, often with a different field type, which is usually why it was recreated.

Look a field up by name and take the first match, and you may be writing to the deleted one. Clio does not reject those writes. Ours reported every field applied for months while some values landed in retired fields. Filter out deleted definitions, and when two live ones collide, let the type your code writes decide.

9. Search and display numbers lag behind writes

Full-text document search is index-backed and lags uploads by seconds to minutes. If someone saves a file and approves it right away, a search can hand you the older version. To find the newest document on a matter, filter by matter_id and sort by updated_at. That filter is real time and covers every folder.

A matter display number is built from the client name when the matter is created. Rename the contact and the client name changes at once, but the display number catches up on Clio's side some minutes later, and no API call forces it. If folder names or task titles depend on it, poll for the change before renaming them.

10. Trust and payments: check the account and the timing

A firm can hold trust money in more than one bank account. An InsufficientFunds error on a trust transaction is per matter and per bank account, so a hard-coded default account fails whenever a matter's money sits in the other one, even with plenty in trust overall. Read the matter's account balances first and post against the trust account that holds the funds.

A client payment through Clio can sit as pending for over an hour before it clears. If your intake waits on paid before opening the matter, show staff that the payment is clearing so nobody calls it stuck.

To split a bill into fee and costs, read its line items: kind is Service or Expense, and the two add up to the bill subtotal. The bill itself does not carry the split.

11. Two features most integrations miss

Every matter has a maildrop address. CC it on email you send about the matter and Clio saves the message to the matter as an email log. It is a free audit trail, and you get it by adding maildrop_address to the fields on the matter. One catch, per Clio's help center (checked 2026-11-19): the maildrop only accepts email from the address the user signs in to Clio with and that user's aliases. Send from a staff member's Clio address, and do not expect a client's reply to the thread to be filed by the maildrop.

Custom actions put your own buttons in a matter's Actions menu. They are scoped to the OAuth app and to the user whose token created them, per Clio's docs, so there is no firm-wide install: each person authorizes once. You also cannot remove actions another app created without that app's token.

Skip the plumbing

See the Clio API working inside a firm brain

FirmOps builds and runs the integration on Clio's API, with every lesson on this page already handled, and connects it to your email, files and the AI you use. Bring one Clio job you want off your team's plate.

Request demo

A checklist before you ship a Clio integration

  • Every request goes through one rate gate per token, with a timeout.
  • Every list call follows meta.paging.next, and no limit is above 200.
  • Every filter you rely on has been proved with a boundary test.
  • Every write is read back: the document is fully uploaded, the field holds the new value, the task shows complete.
  • Changes from Clio arrive by polling with updated_since from a saved checkpoint, not by webhook alone.
  • Custom fields are looked up by id or filtered for deleted definitions, never first match by name.
  • Trust writes pick the bank account that holds the matter's money.

Where a firm brain fits

Most firms do not want to own any of this. They want staff to ask about a matter and get the answer from Clio, the email thread and the documents together, and they want the routine writes done without retyping. That is what FirmOps builds: a firm brain, an MCP server on Clio's API connected to your email, files, phones and the AI your firm already uses, like Claude or ChatGPT. It reads first. Anything it changes in Clio is shown as a preview and a person confirms it, and the write is logged.

It is not Clio-only: the same layer runs on Filevine or SmartAdvocate. And FirmOps is not an MSO; your team and Clio keep running the cases. See the FirmOps MCP server, how to connect Claude or ChatGPT to Clio, and which Clio integrations are worth it.

Clio API questions

Does Clio have an API?

Yes. Clio Manage has a REST API, version 4, documented at docs.developers.clio.com. It covers matters, contacts, documents, activities, bills, tasks, calendar entries, notes, custom fields and more, and it is how most apps in the Clio App Directory connect.

How do you authenticate with the Clio API?

OAuth 2.0. You register an app in the Clio developer portal for your region, a Clio user approves it, and you get an access token and refresh token for that user. Tokens are region-specific: a token from one region is not valid against another region's API.

What is the Clio API base URL?

It depends on the region of the Clio account: app.clio.com/api/v4 in the US, ca.app.clio.com in Canada, eu.app.clio.com for EMEA and au.app.clio.com in Australia, each with /api/v4. Clio says the base URL must match the region of the user's account.

What is the Clio API rate limit?

Clio documents a default of 50 requests per minute per access token during peak hours, higher off-peak. Over the limit you get 429 Too Many Requests with a Retry-After header. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Are Clio webhooks reliable?

Not enough to be the only way you hear about changes. In our production use, matter webhooks missed events, and Clio's docs say webhooks expire (3 days by default, 31 at most) and can be suspended after delivery failures. Poll with updated_since from a saved checkpoint and use webhooks as a speed-up.

How many records does the Clio API return per page?

In our use, 200 at most. A larger limit is silently capped. Use cursor pagination by following meta.paging.next, since offset paging fails once a result set grows past a threshold.

Can I connect Clio to ChatGPT or Claude through the API?

Yes, usually through an MCP server, which exposes Clio API calls as tools an AI can use under the user's own login. The rate limit, paging and write quirks on this page all still apply underneath. The options are compared on our Clio MCP page.

Do I need a developer to use the Clio API?

To build on it directly, yes, and the quirks above are why it takes longer than the docs suggest. Many firms never touch it: they use apps from the Clio App Directory, Zapier, or a firm brain that someone else builds and runs on top of the API.