Professional API: Getting started

Read your own practice data (profile, appointments, approaches, matters and engagement letters) from your own systems, and create will drafts for your clients.

Last reviewed

What the professional API is

A view of your practice data, and one write surface for will drafts, for your own systems.

Scope of the API

The Professional API lets your practice management software, CRM or internal dashboard read the data TheWILL.ai already holds for your practice. Every endpoint lives under /api/v1/pro/ext/ and returns JSON.

The read collections are read-only: they have no create, update or delete endpoints. The one write surface is will drafts for your own clients at /api/v1/pro/ext/wills/, which needs its own scope and a plan that includes it (see Creating will drafts below). Anything else that changes data is still done in the professional dashboard.

Who can use it

API access is part of the Legal Growth, Legal Enterprise and Founding Member Legal Growth plans. On other plans the endpoints are present but refuse every request, because those plans include no API allowance.

Note

Nothing needs to be activated separately. As soon as your plan includes API access, the API keys page (/account/developer/keys) lets you create live keys, and the Usage and logs page (/account/developer/usage) shows your current allowance.

Authentication

Creating a key and sending it with every request.

Creating a key

  1. Open the API keys page at /account/developer/keys and choose Live on the Test / Live switch (choose Test for a key that works on demo data)
  2. Create a key and give it a descriptive name, so you can tell your integrations apart later
  3. Choose what the key may read. “Everything in your practice” (pro:read) is selected by default and reads every collection. To give an integration less, choose individual areas instead: Practice, Clients, Matters, Documents, Billing, Compliance or Team (pro:clients:read, pro:billing:read and so on). A key limited to areas reads only those areas’ endpoints, and cannot start or download a full practice export
  4. If your plan includes will creation you can also include pro:wills:write. Scopes never imply one another, so a key needs a read scope to read and pro:wills:write to create will drafts
  5. Copy the key straight away and store it in a secrets manager or environment variable

Screenshot, for illustration only

The Developer page under Account, where API keys and webhook endpoints are created and managedThe Developer page under Account, where API keys and webhook endpoints are created and managed
The Developer page under Account, where API keys and webhook endpoints are created and managedThe Developer page under Account, where API keys and webhook endpoints are created and managed
The Developer overview. Open API keys in the sub-navigation to create an API key, choose its scopes and copy it before you send your first request.

Important

The key is shown once, at creation. Only a one-way hash is stored, so it cannot be recovered afterwards. If you lose a key, revoke it and create a replacement.

Sending the key

Professional keys carry the same twai_ prefix as consumer keys (older keys beginning pk_ keep working) and travel in the Authorization header using the Bearer scheme:

Authorization: Bearer twai_your_api_key_here

  • A missing or malformed key returns 401
  • A valid key without the scope an endpoint needs returns 403. For a read endpoint the response lists the scopes that would be accepted under accepted_scopes: pro:read or that endpoint’s area scope. Will drafts need pro:wills:write
  • A valid, correctly scoped key on a plan without API access also returns 403, rather than an upgrade prompt dressed up as a success

Rotating a key

Rotate a key on a regular schedule, when someone who knew it leaves the firm, and straight away if it may have leaked. Choose Rotate on the key in the Developer hub. The key keeps its name, scopes, expiry and usage history, and you get a new secret, shown once. You choose what happens to the old secret:

  • Keep the old key working for 24 hours, so you can move your systems across without a gap
  • Stop the old key now, for a key you believe has leaked

Revoking a key stops it at once.

Your first call

Confirm the key works before you build anything on it.

Fetch your profile

  1. Make a GET request to /api/v1/pro/ext/me/ with your key in the Authorization header
  2. A working key returns your professional profile. If the account has no professional profile attached, the response is a 404 carrying {"detail": "No professional profile found for this account."}
  3. A 401 means the key is wrong, revoked or expired; a 403 means the key lacks pro:read or the plan has no API access

Tip

Start with /api/v1/pro/ext/me/ rather than a collection. It is the cheapest call that proves the key, the scope and the plan entitlement are all in order.

Every endpoint, field and error is described in the API reference. Try requests in the interactive console, or download the OpenAPI schema to generate a client or import it into an API tool of your choice.

Try it in the API reference first

You can make this call, or any other, without writing code. Every endpoint on the API reference page has a Try it panel: fill in its fields, choose Send request and read the status, the allowance left and the response body. Copy as cURL gives you the same call with YOUR_API_KEY in place of a real key.

  • Demo data by default: the panel runs on your demo workspace, needs no key and counts against your test allowance
  • A live key for read-only checks: if your plan includes API access, a read (GET) endpoint offers Use a live key. A pasted live key runs the call on your practice’s real data, labelled Live data, and counts against that key’s allowance
  • The pasted key is never saved: it is kept on that page only, never in your browser, your account or the page address. Forget key, or leaving the page, clears it
  • Live calls are logged: a call made with a pasted key appears in that key’s request log and on the Usage and logs page, like any call your own software makes
  • Changes only on demo data: endpoints that create or change something, such as will drafts, can be tried on demo data only. A live key runs read requests here and nothing else

Screenshot, for illustration only

An endpoint in the API reference with its Try it panel open, labelled Demo data, showing the request fields, Send request and Copy as cURLAn endpoint in the API reference with its Try it panel open, labelled Demo data, showing the request fields, Send request and Copy as cURL
An endpoint in the API reference with its Try it panel open, labelled Demo data, showing the request fields, Send request and Copy as cURLAn endpoint in the API reference with its Try it panel open, labelled Demo data, showing the request fields, Send request and Copy as cURL
A Try it panel in the API reference, labelled Demo data. Fill in the fields, then choose Send request, or Copy as cURL to take the same call to your terminal.

The read collections

What the API exposes, and what it deliberately does not.

Endpoints

  • /api/v1/pro/ext/me/: your professional profile
  • /api/v1/pro/ext/appointments/: list, plus a detail view per appointment
  • /api/v1/pro/ext/approaches/: list, plus a detail view per approach
  • /api/v1/pro/ext/matters/: list only. There is no bare matter detail endpoint; the matter brief is fetched from /api/v1/pro/ext/matters/{id}/brief/
  • /api/v1/pro/ext/engagement-letters/: list, plus a detail view per engagement letter

List responses are paginated, 100 records per page by default.

Matter briefs are consent-gated

A matter brief leaves the platform only while the client’s consent for that matter is live. The consent is re-checked on every single call, never cached, and each fetch is written to the matter’s disclosure log, recording the key prefix used but never the key itself.

Note

The brief endpoint also carries its own hourly cap, separate from your plan allowance, and it is shared with the signed bundle download. It is there to keep bulk extraction of client material off the table, so design your integration to fetch a brief when you need it rather than sweeping them on a schedule.

Creating will drafts

Create a will draft for one of your own clients, poll it, and retry safely.

Who can create will drafts

Will creation is part of the Legal Growth, Legal Enterprise and Founding Member Legal Growth plans. It needs a key carrying the pro:wills:write scope, which the Developer hub offers only while your plan includes will creation.

Other plans do not include will creation. The hourly will-draft budget for each plan is listed under Partner will creation in the Rate limits section below.

That hourly budget applies on top of your ordinary plan allowance, and each draft also uses one will-generation credit from your plan; when the credits are used up, a create returns 402. Polling and cancelling use no credits. Your subscription record reports partner_will_api_enabled and partner_will_create_rate_limit_per_hour, so an integration can read its own entitlement.

Note

Every draft is generated on our own servers. A will created through the API is never sent to an external AI provider, and a request that names one is refused.

Endpoints

  • POST /api/v1/pro/ext/wills/: create a will draft and queue its generation
  • GET /api/v1/pro/ext/wills/{id}/: one will you created, and its generation status
  • POST /api/v1/pro/ext/wills/{id}/cancel/: stop a generation that has not finished

The request

  • professional_client_id: the identifier of one of your own active clients. Any other identifier returns 404
  • client_reference (optional): your own reference for the will, up to 255 characters
  • will: an object of named sections. jurisdiction and testator are required; residence, family, assets, gifts, funeral, executors and witnesses are optional

Each section is checked against the same rules as the will interface in the dashboard, and the whole request is checked before anything is created, so a 400 means nothing was stored. An unknown field or section is a 400, never silently dropped: a refused section comes back under will, keyed by section name. Replace BASE_URL with the address you sign in at:

curl -X POST "BASE_URL/api/v1/pro/ext/wills/" \
  -H "Authorization: Bearer twai_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d3f9a52-client-4471-will-1" \
  -d '{
    "professional_client_id": "YOUR_CLIENT_ID",
    "client_reference": "MATTER-4471",
    "will": {
      "jurisdiction": {
        "will_country": "GB",
        "will_state": "ENG",
        "will_state_name": "England",
        "jurisdiction": "GB-ENG",
        "user_country": "GB",
        "date_of_birth": "1970-05-14",
        "will_type": "solo"
      },
      "testator": {
        "first_name": "Harriet",
        "last_name": "Blackwood"
      }
    }
  }'

The response and its status

A create answers 202 with a Location header to poll and a body carrying identifiers and status only, never the client’s details or the will’s content:

{
  "id": "3f2b6c1e-8d4a-4b7e-9c21-5a0e7d9f1b44",
  "status": "pending",
  "professional_client_id": "YOUR_CLIENT_ID",
  "client_reference": "MATTER-4471",
  "created_at": "2026-09-24T10:15:00Z",
  "updated_at": "2026-09-24T10:15:00Z"
}

status is one of pending, processing, completed, failed or cancelled. Poll GET /api/v1/pro/ext/wills/{id}/ to follow it. A failed generation is reported in status, not as an HTTP error; create a new draft to try again. Cancelling a will with nothing generating returns 400.

Retrying safely with Idempotency-Key

  • Every create must carry an Idempotency-Key header, up to 255 characters and unique to that will; without one the request returns 400
  • Sending the same key and the same body again within 24 hours returns the will the first request created, with an Idempotent-Replayed: true header, and does not create a second will
  • Reusing a key with a different body returns 422; use a new key for a new will
  • A refused request (400, 402, 404 or 422) stores nothing, so you can correct it and send it again with the same key

Tip

Generate the key once per will in your own system and store it with the request. After a timeout or a dropped connection, resend the same request with the same key rather than a fresh one.

Rate limits

How much you may call, and where to read your own allowance.

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.

Partner will creation

POST /api/v1/pro/ext/wills/ only, on top of the Professional API budget.

  • Legal Growth: 30 requests per hour
  • Legal Enterprise: 300 requests per hour
  • Founding Member Legal Growth: 30 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:wills:write.

Matter briefs and will documents

GET /api/v1/pro/ext/matters/{id}/brief/, GET /api/v1/pro/ext/wills/{id}/document/ and one-off brief bundles, sharing one budget, on top of the Professional API budget.

  • Every plan: 30 requests per hour

Shared by every key you hold, so a new key never adds to it. Scopes: pro:read.

Professional MCP agent tools

MCP tool calls, counted separately from your REST budget.

  • 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.

These figures come from the limits the API enforces, also served as JSON at /api/v1/portfolio/rate-limits/.

Seeing your own limit

The Developer hub shows the allowance your plan currently grants, the number of keys you may hold, and the scope your keys are issued with. The same figures come back on your subscription record as rate_limit_per_hour (an integer, or null where the plan is unlimited), so an integration can read its own ceiling rather than hard-coding one.

Tip

Every response reports your allowance in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. The allowance is per user, shared by all of your keys, and a per-minute burst cap derived from your hourly rate stops it being spent in a few seconds; pace your calls from the headers and back off when you are told to.

When you exceed it

An over-limit request returns 429 with a Retry-After header and a body carrying error_code of RATE_LIMITED plus a wait_time in seconds. Honour whichever you read; do not retry immediately.

If you need to know about changes as they happen, subscribe to webhooks instead of polling.

Errors and scoping

The response shapes to code against, and why a 404 is not always a missing record.

Error shapes

Two shapes are in use on this surface, so handle both rather than assuming one:

  • The scoping and profile refusals carry a detail key, for example {"detail": "Not found."}
  • Authentication, permission and throttling refusals carry error and status_code, and the 429 additionally carries message, error_code and wait_time

404 rather than 403

Asking for a record that belongs to another practice returns 404, not 403, and it is the identical body you get for an identifier that does not exist anywhere. The queryset behind each collection is filtered to your own practice before the lookup happens, so a record outside it is simply not there to be found.

This is deliberate. A 403 would confirm that the identifier exists and belongs to someone, which is exactly the signal an identifier-guessing attack needs. The matter brief goes further still: "not yours" and "consent is not live" return byte-identical responses, so the presence or absence of a client’s consent cannot be probed from outside.

Note

When you get a 404 on an identifier you believe is yours, check the account the key belongs to before assuming the record was deleted.

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.