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_size sets 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 Link response header with rel="next" and rel="prev".
  • Without cursor, lists use numbered pages (?page=2) and include a total count. 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:

  1. Walk GET /api/v1/pro/ext/appointments/?cursor=&page_size=500 to the end and save every row.
  2. Note the newest updated_at you received, for example 2026-01-31T09:00:00Z.
  3. Next time, request GET /api/v1/pro/ext/appointments/?cursor=&updated_since=2026-01-31T09:00:00Z and walk that to the end.
  4. Upsert each row by its id, then note the new newest updated_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 cursor

The 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, next carries on through pages of deletion rows only, so keep following next until it is null.
  • 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_since is older than that, the API answers 410 Gone with the code sync_window_expired. Walk the whole collection again without updated_since, then resume from the newest updated_at you 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.

  1. POST /api/v1/pro/ext/exports/ with no body starts an export and returns the job with 202 Accepted. If one is already being prepared, you get 409 Conflict with that job instead.
  2. Poll GET /api/v1/pro/ext/exports/<id>/ until can_download is true.
  3. Fetch the file from download_url. The link is signed, needs no key, and expires after a few minutes (see download_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/.

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

We use cookies to improve your experience. See our Cookie policy (opens in a new tab) for details.