Skip to main content
API docs by Redocly

Clio Platform API (v1)

Download OpenAPI specification:Download

Clio Platform API Support: api@clio.com License: Proprietary

Public REST API for Clio's platform-level (API Hub) services.

These are global, product-independent endpoints — currently the multi-product webhooks platform. Authenticate with an OAuth 2.0 bearer token (Authorization: Bearer <jwt>) issued through the Clio API Hub. Pass the OpenAPI version with X-API-Version: YYYY-MM-DD to pin a specific contract, or unstable to opt in to the latest spec.

Platform-level operations require a valid token and no scope of their own. Resource scopes (e.g. grow_lead_inbox_read) gate which event types a subscription may include, and are not declared below — they belong to the products that own those events.

Successful responses use { "data": ... } envelopes (with { "meta": { "paging": ... } } on paginated collections; meta is omitted when there is only one page). Errors use { "error": "<code>" }, sometimes with an additional details list of strings carrying context for that code.

Webhook Subscriptions

Operations for managing webhook subscriptions on the authenticated entity, and for reading the deliveries recorded against them

List webhook subscriptions

Returns a cursor-paginated list of the calling application's webhook subscriptions for the authorized entity. signing_secret is never included. meta is omitted entirely when there is neither a next nor a previous page.

query Parameters
page_token
string

Opaque token for cursor-based pagination. Follow the links in meta.paging rather than constructing one; a malformed or tampered token is a 400 invalid_argument_page_token.

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Responses

Response samples

Content type
application/json
{}

Create a webhook subscription

Creates a webhook subscription for the authorized entity. The subscription starts as pending and must be activated before events are delivered. Every requested event type must be one the token already holds the resource scope for. The response is one of only two places signing_secret is returned.

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Request Body schema: application/json
required
url
string <uri> <= 2048 characters

Required. The HTTPS endpoint events are delivered to. Must not resolve to a loopback, private, or link-local address.

event_types
Array of strings

Required, and must be non-empty. The events to subscribe to, each formatted as <product>.<resource_type>.<event_type>.

schema_version
string <= 32 characters

The event payload schema version to pin to, as a YYYY-MM-DD date. Defaults to the latest published payload version. If sent, it must be a published payload version, or the request is rejected.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a webhook subscription by ID

Returns a single webhook subscription belonging to the calling application and the authorized entity. signing_secret is never included. A subscription owned by another application or entity returns 404, not 403.

path Parameters
id
required
integer <int64>
Example: 123

Unique identifier of the webhook subscription

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a webhook subscription

Updates a webhook subscription. event_types replaces the full set rather than appending to it; supplying an empty array disables an active subscription. Changing url returns the subscription to pending from any state, so it must be re-activated. status is not writable: a request body carrying it is rejected with a 422 validation_failed, since state moves through activate, enable and disable. signing_secret is preserved and is not returned.

path Parameters
id
required
integer <int64>
Example: 123

Unique identifier of the webhook subscription

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Request Body schema: application/json
optional
url
string <uri> <= 2048 characters

The HTTPS endpoint events are delivered to. Must not resolve to a loopback, private, or link-local address.

event_types
Array of strings

The complete set of events to subscribe to, each formatted as <product>.<resource_type>.<event_type>. Replaces the existing set. An empty array disables an active subscription.

schema_version
string <= 32 characters

The event payload schema version to pin to, as a YYYY-MM-DD date. Must be a published payload version, or the request is rejected with a 422 validation_failed.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a webhook subscription

Permanently deletes the webhook subscription and stops all delivery to it. This action cannot be undone. To stop delivery reversibly, use POST /webhook_subscriptions/{id}/disable.

path Parameters
id
required
integer <int64>
Example: 123

Unique identifier of the webhook subscription

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "details": [
    ]
}

Activate a webhook subscription

Activates a pending or suspended subscription. Clio issues a challenge request to the subscription's URL, signed with its signing_secret; the endpoint must echo the challenge back correctly. On success the subscription moves to active. An already-active subscription is returned unchanged without a challenge. A subscription with no event_types is rejected, and a disabled one is rejected pointing at POST /webhook_subscriptions/{id}/enable. Neither issues a challenge. signing_secret is not returned.

path Parameters
id
required
integer <int64>
Example: 123

Unique identifier of the webhook subscription

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Disable a webhook subscription

Stops delivery to an active subscription, reversibly, and moves it to disabled. Recover with POST /webhook_subscriptions/{id}/enable, which needs no challenge. An already-disabled subscription is returned unchanged. A pending or suspended subscription is rejected with a 422: neither is delivering, so there is nothing to disable.

path Parameters
id
required
integer <int64>
Example: 123

Unique identifier of the webhook subscription

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Enable a webhook subscription

Resumes delivery for a disabled subscription, moving it to active with no challenge, because disabled is only reachable from a subscription that already answered one. An already-active subscription is returned unchanged. A pending or suspended subscription is rejected with a 422 pointing at POST /webhook_subscriptions/{id}/activate. A subscription with no event_types is rejected, so restore an event type first.

path Parameters
id
required
integer <int64>
Example: 123

Unique identifier of the webhook subscription

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Regenerate a webhook subscription's signing secret

Replaces the subscription's signing secret with a new one and returns it. The previous secret stops working immediately, and the subscription's status is unchanged. This is one of only two places signing_secret is returned — it is never readable afterwards, so store it on receipt.

path Parameters
id
required
integer <int64>
Example: 123

Unique identifier of the webhook subscription

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List a webhook subscription's deliveries

Returns a cursor-paginated list of this subscription's deliveries — what Clio recorded for it, and how delivery of each one went. Only delivery metadata is returned — never payload data, which is why this operation needs no resource scope. Results are ordered by event_id rather than occurred_at, and are retained for 7 days after Clio records them. meta is omitted entirely when there is neither a next nor a previous page. A subscription owned by another application or authorized entity returns 404, not 403.

path Parameters
webhook_subscription_id
required
integer <int64>
Example: 123

Unique identifier of the webhook subscription whose deliveries are listed

query Parameters
page_token
string

Opaque token for cursor-based pagination. Follow the links in meta.paging rather than constructing one; a malformed or tampered token is a 400 invalid_argument_page_token.

event_type
string
Example: event_type=grow.inbox_lead.submitted

Return only deliveries whose event is of this type, formatted as <product>.<resource_type>.<event_type>. Any other shape is a 400 invalid_argument_event_type; a well-formed type that matches nothing is an empty list rather than an error.

after
string
Example: after=01ARZ3NDEKTSV4RRFFQ69G5FAV

Return only deliveries whose event_id is greater than this one. That always means newer than the anchor, whichever order is requested, and the anchor itself is never returned. To resume after an outage, walk with order=asc and anchor on the newest event_id you have processed; under the default order=desc this bounds how far back the page reaches rather than acting as a resume point. Must be a ULID; anything else is a 400 invalid_argument_after.

occurred_after
string
Example: occurred_after=2026-08-07T10:30:00.000Z

Inclusive lower bound on occurred_at. Must be a full ISO-8601 timestamp — a bare date, or anything that cannot be parsed, is a 400 invalid_argument_occurred_after rather than being widened to midnight.

occurred_before
string
Example: occurred_before=2026-08-07T18:00:00.000Z

Inclusive upper bound on occurred_at. Must be a full ISO-8601 timestamp — a bare date, or anything that cannot be parsed, is a 400 invalid_argument_occurred_before rather than being widened to midnight.

limit
string
Example: limit=100

Maximum number of deliveries to return per page. Values above 100 are capped at 100 rather than rejected. A value that is not a positive integer is a 400 invalid_argument_limit. Defaults to 100.

status
string
Example: status=failed

Return only deliveries in this state: pending, succeeded or failed. Any other value is a 400 invalid_argument_status.

order
string
Example: order=desc

The direction to walk event_id in. Only asc and desc are accepted; anything else is a 400 invalid_argument_order. Defaults to desc, newest first.

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {}
}

Get one of a webhook subscription's deliveries

Returns a single delivery, including every attempt Clio made to deliver it. Only delivery metadata is returned, never payload data.

path Parameters
webhook_subscription_id
required
integer <int64>
Example: 123

Unique identifier of the webhook subscription whose deliveries are listed

id
required
string
Example: 66b3f0c2e1a4d9c7b8a02f31

Unique identifier of the delivery, as carried on the id field of the webhook you received. An id that matches nothing visible to you is a 404.

header Parameters
X-API-Version
string
Example: 2026-08-07

Pins the request to a specific OpenAPI contract. Pass a date in YYYY-MM-DD format to select that version, or unstable to opt in to the latest spec. Omit to use the default (latest stable) contract. An unrecognised value falls back to the default rather than being rejected.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Grow Webhook Events

Events sent to your webhook subscriptions from Clio Grow. Each event is a POST with a JSON body.

These docs describe the latest version of each payload. Every event is delivered in your subscription's schema_version, and carries that schema_version. A new version does not change what you receive until you update your subscription.

Inbox lead submitted Webhook

Sent when a new lead arrives in a firm's inbox. Requires the grow_lead_inbox_read or grow_lead_inbox_all_read scope.

header Parameters
X-Clio-Signature
required
string
Example: v1=9a103be2201ae758992733a91f02903f9a103be2201ae758992733a91f02903f

Set by Clio on every webhook request. HMAC-SHA256 signature over the raw request body, prefixed with the signature version. Keyed with the subscription's signing_secret, over the string <timestamp>:<delivery_id>:<subscription_id>:<raw body>, taking each value from the matching header. Compare it in constant time, and compute the digest over the body exactly as received rather than a re-serialized copy.

X-Clio-Timestamp
required
integer <int64>
Example: 1761600000

Set by Clio on every webhook request. Unix timestamp the signature was generated at. It is covered by the signature, so it cannot be altered without invalidating it. Reject requests older than five minutes to limit replay: a captured request verifies indefinitely otherwise. Each delivery attempt is signed afresh, so retries carry a current timestamp.

X-Clio-Delivery-ID
required
string
Example: 6708f1c2a4b3c5d6e7f80912

Set by Clio on every webhook request, identifying it. On an event delivery this is the delivery's ID, and every retry of that delivery reuses it. On an activation challenge it is a one-off value prefixed with challenge_ that does not correspond to a readable delivery. Route on that prefix: only answer a challenge when it is present, and never process such a request as an event.

X-Clio-Subscription-ID
required
integer <int64>
Example: 123

Set by Clio on every webhook request. The ID of the webhook subscription the request belongs to.

Request Body schema: application/json
required
event_id
required
string

Unique ID for the event. A retried delivery sends the same ID, so use it to discard duplicates.

event_type
required
string
Value: "grow.inbox_lead.submitted"
schema_version
required
string <date>

The version of payload in this delivery.

occurred_at
required
string <date-time>

When the event happened in Clio Grow, in UTC.

required
object

Responses

Request samples

Content type
application/json
{
  • "event_id": "01JA6Z3N8Q2V5W7X9Y1B3C5D7E",
  • "event_type": "grow.inbox_lead.submitted",
  • "schema_version": "2026-01-01",
  • "occurred_at": "2026-01-15T17:04:12Z",
  • "payload": {
    }
}

Inbox lead accepted Webhook

Sent when a firm accepts an inbox lead, creating a contact and, optionally, a matter. Requires the grow_lead_inbox_read or grow_lead_inbox_all_read scope.

header Parameters
X-Clio-Signature
required
string
Example: v1=9a103be2201ae758992733a91f02903f9a103be2201ae758992733a91f02903f

Set by Clio on every webhook request. HMAC-SHA256 signature over the raw request body, prefixed with the signature version. Keyed with the subscription's signing_secret, over the string <timestamp>:<delivery_id>:<subscription_id>:<raw body>, taking each value from the matching header. Compare it in constant time, and compute the digest over the body exactly as received rather than a re-serialized copy.

X-Clio-Timestamp
required
integer <int64>
Example: 1761600000

Set by Clio on every webhook request. Unix timestamp the signature was generated at. It is covered by the signature, so it cannot be altered without invalidating it. Reject requests older than five minutes to limit replay: a captured request verifies indefinitely otherwise. Each delivery attempt is signed afresh, so retries carry a current timestamp.

X-Clio-Delivery-ID
required
string
Example: 6708f1c2a4b3c5d6e7f80912

Set by Clio on every webhook request, identifying it. On an event delivery this is the delivery's ID, and every retry of that delivery reuses it. On an activation challenge it is a one-off value prefixed with challenge_ that does not correspond to a readable delivery. Route on that prefix: only answer a challenge when it is present, and never process such a request as an event.

X-Clio-Subscription-ID
required
integer <int64>
Example: 123

Set by Clio on every webhook request. The ID of the webhook subscription the request belongs to.

Request Body schema: application/json
required
event_id
required
string

Unique ID for the event. A retried delivery sends the same ID, so use it to discard duplicates.

event_type
required
string
Value: "grow.inbox_lead.accepted"
schema_version
required
string <date>

The version of payload in this delivery.

occurred_at
required
string <date-time>

When the event happened in Clio Grow, in UTC.

required
object

Responses

Request samples

Content type
application/json
{
  • "event_id": "01JA6Z3N8Q2V5W7X9Y1B3C5D7E",
  • "event_type": "grow.inbox_lead.accepted",
  • "schema_version": "2026-01-01",
  • "occurred_at": "2026-01-15T17:04:12Z",
  • "payload": {
    }
}

Inbox lead rejected Webhook

Sent when a firm rejects an inbox lead. Requires the grow_lead_inbox_read or grow_lead_inbox_all_read scope.

header Parameters
X-Clio-Signature
required
string
Example: v1=9a103be2201ae758992733a91f02903f9a103be2201ae758992733a91f02903f

Set by Clio on every webhook request. HMAC-SHA256 signature over the raw request body, prefixed with the signature version. Keyed with the subscription's signing_secret, over the string <timestamp>:<delivery_id>:<subscription_id>:<raw body>, taking each value from the matching header. Compare it in constant time, and compute the digest over the body exactly as received rather than a re-serialized copy.

X-Clio-Timestamp
required
integer <int64>
Example: 1761600000

Set by Clio on every webhook request. Unix timestamp the signature was generated at. It is covered by the signature, so it cannot be altered without invalidating it. Reject requests older than five minutes to limit replay: a captured request verifies indefinitely otherwise. Each delivery attempt is signed afresh, so retries carry a current timestamp.

X-Clio-Delivery-ID
required
string
Example: 6708f1c2a4b3c5d6e7f80912

Set by Clio on every webhook request, identifying it. On an event delivery this is the delivery's ID, and every retry of that delivery reuses it. On an activation challenge it is a one-off value prefixed with challenge_ that does not correspond to a readable delivery. Route on that prefix: only answer a challenge when it is present, and never process such a request as an event.

X-Clio-Subscription-ID
required
integer <int64>
Example: 123

Set by Clio on every webhook request. The ID of the webhook subscription the request belongs to.

Request Body schema: application/json
required
event_id
required
string

Unique ID for the event. A retried delivery sends the same ID, so use it to discard duplicates.

event_type
required
string
Value: "grow.inbox_lead.rejected"
schema_version
required
string <date>

The version of payload in this delivery.

occurred_at
required
string <date-time>

When the event happened in Clio Grow, in UTC.

required
object

Responses

Request samples

Content type
application/json
{
  • "event_id": "01JA6Z3N8Q2V5W7X9Y1B3C5D7E",
  • "event_type": "grow.inbox_lead.rejected",
  • "schema_version": "2026-01-01",
  • "occurred_at": "2026-01-15T17:04:12Z",
  • "payload": {
    }
}

Matter accepted Webhook

Sent when a firm accepts a Clio Grow matter, creating a matter in Clio Manage. Requires the grow_matter_read scope.

header Parameters
X-Clio-Signature
required
string
Example: v1=9a103be2201ae758992733a91f02903f9a103be2201ae758992733a91f02903f

Set by Clio on every webhook request. HMAC-SHA256 signature over the raw request body, prefixed with the signature version. Keyed with the subscription's signing_secret, over the string <timestamp>:<delivery_id>:<subscription_id>:<raw body>, taking each value from the matching header. Compare it in constant time, and compute the digest over the body exactly as received rather than a re-serialized copy.

X-Clio-Timestamp
required
integer <int64>
Example: 1761600000

Set by Clio on every webhook request. Unix timestamp the signature was generated at. It is covered by the signature, so it cannot be altered without invalidating it. Reject requests older than five minutes to limit replay: a captured request verifies indefinitely otherwise. Each delivery attempt is signed afresh, so retries carry a current timestamp.

X-Clio-Delivery-ID
required
string
Example: 6708f1c2a4b3c5d6e7f80912

Set by Clio on every webhook request, identifying it. On an event delivery this is the delivery's ID, and every retry of that delivery reuses it. On an activation challenge it is a one-off value prefixed with challenge_ that does not correspond to a readable delivery. Route on that prefix: only answer a challenge when it is present, and never process such a request as an event.

X-Clio-Subscription-ID
required
integer <int64>
Example: 123

Set by Clio on every webhook request. The ID of the webhook subscription the request belongs to.

Request Body schema: application/json
required
event_id
required
string

Unique ID for the event. A retried delivery sends the same ID, so use it to discard duplicates.

event_type
required
string
Value: "grow.matter.accepted"
schema_version
required
string <date>

The version of payload in this delivery.

occurred_at
required
string <date-time>

When the event happened in Clio Grow, in UTC.

required
object

Responses

Request samples

Content type
application/json
{
  • "event_id": "01JA6Z3N8Q2V5W7X9Y1B3C5D7E",
  • "event_type": "grow.matter.accepted",
  • "schema_version": "2026-01-01",
  • "occurred_at": "2026-01-15T17:04:12Z",
  • "payload": {
    }
}