Professional API: Syncing your practice data
Copy your practice data into your own systems once, then fetch only what has changed since.
Last reviewed
What you can sync
Every list on the TheWILL.ai Professional API supports the same sync pattern: appointments, enquiries, clients, matters, will reviews,engagement letters, invoices, time entries, rate cards, commission statements, referrals, tasks, complaints, reviews, documents, messages and your team.
You need a professional API key with the pro:read scope, sent as Authorization: Bearer <your key>. The getting started guide shows how to create one.
Walking a whole collection
Add ?cursor= (with an empty value) to any list request to switch to cursor pagination. Rows come back oldest change first, and each response carries a next link to the following page. Keep following next until it is null.
page_sizesets how many rows each page holds, up to 500. Larger values are capped rather than refused.- The cursor is opaque. Store and send it back exactly as you received it.
- The same links are also sent in a standard
Linkresponse header withrel="next"andrel="prev". - Without
cursor, lists use numbered pages (?page=2) and include a totalcount. Cursor pages leave the count out.
Fetching only what changed
After the first full walk, ask for changes only with updated_since, an ISO-8601 date or date-time. A worked example:
- Walk
GET /api/v1/pro/ext/appointments/?cursor=&page_size=500to the end and save every row. - Note the newest
updated_atyou received, for example2026-01-31T09:00:00Z. - Next time, request
GET /api/v1/pro/ext/appointments/?cursor=&updated_since=2026-01-31T09:00:00Zand walk that to the end. - Upsert each row by its
id, then note the new newestupdated_at.
The boundary is inclusive, so the row you stopped on last time comes back once more. Upserting by id makes that harmless. A date without a time means midnight UTC, and a time without an offset is read as UTC.
# Keep the key off the command line: write the header to a private file once umask 077 printf 'header = "Authorization: Bearer %s"\n' "$API_KEY" > api.curlrc # Walk everything, then fetch only what changed since your newest updated_at curl --retry 5 "https://thewill.ai/api/v1/pro/ext/appointments/?cursor=&page_size=500" \ --config api.curlrc curl --retry 5 "https://thewill.ai/api/v1/pro/ext/appointments/?cursor=&updated_since=2026-01-31T09:00:00Z" \ --config api.curlrc
import os
import time
import requests
BASE_URL = "https://thewill.ai/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['API_KEY']}"
def sync_appointments(store):
"""Upsert every appointment changed since the last run."""
url = f"{BASE_URL}/pro/ext/appointments/"
params = {"cursor": "", "page_size": 500}
if store.last_seen:
params["updated_since"] = store.last_seen
while url:
response = session.get(url, params=params, timeout=30)
if response.status_code == 429:
time.sleep(int(response.headers.get("Retry-After", "5")))
continue # same page again once the wait is over
response.raise_for_status()
page = response.json()
for row in page["results"]:
store.upsert(row["id"], row) # the boundary row comes back once: upsert, never insert
store.last_seen = max(store.last_seen or "", row["updated_at"])
url, params = page["next"], None # next already carries the cursorThe integration recipes add webhooks to this loop, in Python and Node.js.
Deletions
Appointments, enquiries, clients, engagement letters, invoices, commission statements, referrals, time entries and rate cards record deletions. When a row in one of those is removed, a sync with updated_since tells you so, even when the other side of a referral or a colleague at your firm removed it. Once the changed rows run out you receive deletion rows shaped like {"id": 42, "deleted": true, "deleted_at": "2026-02-01T10:15:00Z"}. Remove those ids from your copy.
- Deletion rows count towards the page size. When there are more than fit,
nextcarries on through pages of deletion rows only, so keep followingnextuntil it isnull. - A deletion row can name an id you never held. Ignore it.
- A rate card or time entry that leaves a list without being deleted (its jurisdiction was removed, or you can no longer see the matter) is not reported. Walk those collections in full from time to time.
- On those collections, deletions are kept for 30 days. If your
updated_sinceis older than that, the API answers410 Gonewith the codesync_window_expired. Walk the whole collection again withoutupdated_since, then resume from the newestupdated_atyou receive.
Webhooks are a nudge, not the record
A webhook tells you something changed so you can run a sync sooner. Deliveries can be missed, so keep a scheduled updated_since sync as well.
Bulk export by key
For a one-off copy of everything, request an export instead of walking each list.
POST /api/v1/pro/ext/exports/with no body starts an export and returns the job with202 Accepted. If one is already being prepared, you get409 Conflictwith that job instead.- Poll
GET /api/v1/pro/ext/exports/<id>/untilcan_downloadis true. - Fetch the file from
download_url. The link is signed, needs no key, and expires after a few minutes (seedownload_expires_in), so poll again for a fresh link if it lapses.
Every export request is recorded in your practice’s audit trail. The full reference for each endpoint is in the professional API reference.
Rate limits
Limits are counted on a sliding window. When you go over one, the API answers 429 Too Many Requests with a Retry-After header telling you how long to wait.
Professional API
Every request to /api/v1/pro/ext/.
- Legal Growth: 2,000 requests per hour
- Support Services Plus: 2,000 requests per hour
- Legal Enterprise: unlimited
- Support Services Enterprise: unlimited
- Founding Member Legal Growth: 2,000 requests per hour
- Founding Member Support Services Plus: 2,000 requests per hour
Shared by every key you hold, so a new key never adds to it. Plans not listed here have no access to this API. Scopes: pro:read, pro:clients:read, pro:matters:read, pro:documents:read, pro:billing:read, pro:compliance:read, pro:team:read, pro:practice:read, pro:org:read, pro:wills:write.
These figures come from the limits the API enforces, also served as JSON at /api/v1/portfolio/rate-limits/.
Related topics
Can’t find what you’re looking for?
Our support team is here to help. Contact us and we’ll get back to you as soon as possible.
Contact us
