Get started with Chronicle API v2
Chronicle API v2 connects your firm's systems, and vendors whose integrations Chronicle has approved and whose access your firm authorizes, to your Chronicle data: clients, case units, eFolder documents and extractions, packets, notes, SSA requests, calendar events, ERE uploads, document refreshes, people and webhooks. Read this page before your first request. Every endpoint, parameter and response is documented in the reference that follows it.
Before you start
Review the Chronicle API Terms of Service before creating a key.
Your Chronicle plan must include API access. Without it, every request returns
403 entitlement_required.An account Admin or Billing owner creates and manages API keys.
Call the API from a server. Keys are secrets, so never put them in browser or mobile code, URLs or logs.
Make your first request
Create a key with only the access your integration needs, then confirm it works with GET /account, which needs no scope.
In Chronicle, open Settings > API and click Create API key.
Enter a Key name and choose when the secret expires.
Under Permissions, choose the scopes your integration needs.
Under Client access, choose All clients or Specific clients, then create the key.
Copy the secret and store it in a secrets manager. We show it only once.
Send it as a bearer token:
curl https://app.chroniclelegal.com/api/v2/account \
-H "Authorization: Bearer chv2_..."The response shows the key's account, its scopes, and which clients it can access. All endpoints are relative to https://app.chroniclelegal.com/api/v2, and only HTTPS is supported.
How keys control access
Each key carries its own scopes and client access, so you can give every tool or vendor its own key with exactly the access it needs.
Scopes are independent: no scope includes another. Each endpoint in the reference lists the scope it requires, and a missing scope returns
403 missing_scope.Client access limits a key to an allowlist of clients. A client the key cannot access returns
404, exactly like one that does not exist.Sensitive fields (SSN, date of birth and SSN last four) are returned only when you ask for them and the key has
clients:sensitive:read.Secrets expire after 90 days by default, and you can choose up to one year. To rotate without downtime, create a new secret from the key's page: the current secret keeps working for an overlap you choose, up to seven days. Revoking a key stops all of its secrets immediately.
Conventions every endpoint follows
These rules apply across the whole API, so build them into your client once.
Responses: a single resource comes back as
{"data": {...}, "request_id": "req_..."}, and lists add apageobject. IDs are strings, timestamps are ISO 8601, and unknown fields or query parameters return422.Pagination: lists return up to 50 items by default and 100 at most. When
page.has_moreistrue, passpage.next_cursorascursorwith the same filters. Cursors expire after 24 hours.Keeping a copy in sync: poll with
updated_sinceusing overlapping time windows, and deduplicate byidandresource_version.Updates: changing a client or a person requires an
If-Matchheader with theETagfrom your latest read. A stale value returns412; read again and retry.Retries: requests that create or change data require an
Idempotency-Key. Reuse the same key when you retry, and we return the original result instead of repeating the action.Background work: packet generation, upload validation, ERE uploads and document refreshes return
202 Acceptedwith a resource you can poll.202means the work was accepted, not that it finished.Rate limits: per minute, 120 requests per key, 600 per account across all keys, and 10 heavy operations per account. Over the limit, requests return
429with aRetry-Afterheader in seconds.Errors: branch on
error.code, notmessage, which is written for people and may change. Retry429,502and503with backoff.
Document and packet download links are bearer URLs valid for five minutes. Anyone with the URL can download the file until it expires, even after the key is revoked, so never log or share them.
Get notified with webhooks
Webhooks tell your endpoint when data in your account changes, so you don't have to poll for everything.
Manage endpoints and signing secrets in the Webhook portal under Settings > API, or with the Webhooks endpoints in the reference. Managing endpoints through the API requires a key with access to all clients.
Verify every delivery's Svix signature against the raw request body, and return a
2xxstatus to acknowledge it.The same event can arrive more than once or out of order, so store each event
idand skip ones you have already processed.Event data is minimal by design. Fetch
links.currentwith a key that holds the event type'srequired_scopeto read the current state.
If you use API v1
Your v1 keys keep working, and v1 and v2 run side by side. They are separate, so plan a v2 integration as new work rather than a find-and-replace.
v2 does not accept v1 keys. Create a v2 key under Settings > API.
v2 uses a different base URL (
https://app.chroniclelegal.com/api/v2) and sends the key asAuthorization: Bearerinstead ofX-API-KEY.v1 and v2 webhook endpoints are managed in separate portals.
The v1 reference stays available in the v1 developer docs.
Get help
Every response includes an X-Request-ID header that matches the request_id in the body. Include it when you email [email protected], and we can find the exact request. Use of the API is covered by the API Terms of Service.