Skip to main content

Frequently Asked Questions

Quick answers to common questions about the Clio API. Each entry links to the relevant reference doc or guide for full details.

Pagination​

How do I retrieve more records than returned in a single page?​

Use cursor pagination and follow the meta.paging.next URL in a loop until it is absent. No record-count limit applies.

OAuth & Tokens​

I'm getting a 401 Unauthorized — what's wrong?​

Most 401s are caused by an expired token (Manage tokens last 30 days; Platform tokens last 24 hours), a revoked token, a missing or malformed Authorization header, or using a token against the wrong regional endpoint.

How do I refresh an expired access token?​

Use your refresh token to POST to the token endpoint. Refresh token behavior differs between the two APIs:

  • Clio Manage: Refresh tokens do not expire and can be reused across multiple refresh calls. They remain valid until explicitly revoked.

  • Clio Platform: Refresh tokens do not have a time-based expiry, but they are rotated on each use. Each time you use a refresh token, you receive a new refresh token and the old one is revoked. Store the new token each time.

  • Clio Manage: Refreshing an Access Token

  • Clio Platform: Refreshing an Access Token

Permissions & 403s​

I have a valid token but I'm getting a 403 Forbidden — why?​

There are two common causes:

  1. Your app didn't request the required OAuth scope, or the user authorized your app before you added the scope. Fix this by updating the required scope in your app settings and prompting affected users to reauthorize.
  2. The user's role in Clio Manage doesn't permit the action. Even with the correct OAuth scope, users can only access data their Clio role allows. The firm administrator needs to adjust the user's role.

Regions & Base URLs​

Which base URL should I use for EU, CA, or AU customers?​

The base URL must match the region of the user's Clio account. A token from one region is not valid against another region's API.

Developer Account & Sandbox​

How do I register a new app and where do I find my Client ID and Client Secret?​

Create an app in your developer portal after signing up. Your Client ID and Secret are on the app's Settings page.

Is there a sandbox or test environment?​

See Is there a sandbox or test environment? in the handbook for full details.

Bills & Invoices​

How do I see which bills have been paid and which are outstanding?​

Use the Bills endpoint and filter by state (awaiting_payment, paid, etc.). The balance field shows the remaining amount outstanding.

Webhooks​

How do I get notified when data changes in Clio?​

Clio can notify your app automatically when something happens — a new contact, an updated bill — so you don't have to poll the API. This is done with webhooks: you subscribe to created, updated, and deleted events on supported models, and Clio pushes them to your callback URL. See What is a webhook? to get started.

What is a webhook?​

A webhook is a way for Clio to send near real-time notifications to your application when something happens (for example, a contact or bill is created). Instead of your app polling the API for changes, Clio pushes events to an HTTPS callback URL you provide. Each delivery includes the model, the event type (created, updated, deleted), and a signature header so you can verify the payload came from Clio.

How do I create a webhook, and which models are supported?​

Make a POST request to the Webhooks endpoint with a model, a list of events (created, updated, deleted), and an HTTPS callback URL. A range of models is supported — see Supported Models for the current list. Your application needs the OAuth scope for the model you're subscribing to, plus the webhooks scope.

The POST doesn't activate the webhook on its own. A new webhook starts in pending status, and Clio sends a handshake request to your URL before delivering any events. You confirm it either by echoing the X-Hook-Secret header back with a 200 response, or by calling the activate endpoint with that secret. Only then does the webhook become enabled and events start flowing.

How do I verify that a webhook payload actually came from Clio?​

Every delivery includes an HMAC-SHA256 signature in the X-Hook-Signature header, computed over the raw request body using the secret you exchanged during the handshake. Compute the same signature on your side and compare the two with a constant-time comparison. If they don't match, reject the request.

I created a webhook but I'm not receiving any events. What's wrong?​

The most common reason is that the endpoint handshake never completed, so the webhook is still in pending status and Clio isn't sending anything. Fetch the webhook with a GET request and check its status: if it's pending, confirm the handshake to activate it (see How do I create a webhook, and which models are supported? above). Also make sure your callback URL uses https — http URLs are rejected — and that it's reachable from the public internet. If the webhook was working before and only recently went quiet, see Why did my webhook stop receiving events? instead.

Why did my webhook stop receiving events?​

If a webhook that was previously delivering events goes quiet, there are two common causes. It may have expired: webhooks last 3 days by default and 31 days at most, so extend expires_at before it lapses. Or it may have been suspended after repeated delivery failures, in which case its status will be suspended and you'll want to look into why your endpoint was erroring or timing out. (If the webhook never delivered any events in the first place, see I created a webhook but I'm not receiving any events instead.)

Getting Started & Building​

Can I build an integration with Clio Grow?​

Yes! As of January 2026, you can build integrations with Clio Grow APIs using the Clio Platform developer portal. The handbook contains instructions on signing up for a Clio Platform account, and we maintain API docs on Clio Platform features as well as an API Reference page for Grow API endpoints.

What's the difference between the Clio Platform and the Clio Manage API?​

The Clio Platform is the current platform for building on Clio Grow APIs, and in future will be the single point of entry for building integrations with all Clio products. The Clio Manage API and developer portal supports existing integrations with Clio Manage. For more information, see the handbook page detailing the differences between Clio Manage and the Clio Platform.

Can you tell me what to build?​

Clio does not currently publicize our product roadmap. If you are curious about trends in the legal technology space, you can reference our Legal Trends Report.

Can Clio help me build my app?​

Clio cannot offer resources for building an integration at this time. If you need additional assistance building your integration, a Clio Certified Consultant may be able to assist.

We also maintain an example application that you can use as a reference for handling authorization and API calls.

What happens if I don't pass the security review?​

The Clio team will highlight areas that need attention so you can build a safe and secure app. Our team will work with you to ensure you meet the correct standards.

I've launched my app. How can I strengthen my relationship with Clio?​

You can find information about our Certified App Program in the "Launch and Grow Your App" section of the handbook.