Matter-brief API

What the matter-brief API is for

The matter-brief API lets your own drafting software pull the instructions for a matter you have been engaged on, so you can work in the tools you already use instead of re-keying a client’s file by hand. It is read-only. Nothing you send can change a matter, and no endpoint here writes.

Client data is never handed over on the strength of your key alone. The list of matters carries no client data at all, and the brief is released only while the client’s own consent for that matter is live. Consent is re-checked on every single fetch, never cached, so a client who withdraws it stops the next call rather than the next month’s.

Authentication and access

Authenticate with a personal API key as a bearer token. Keys begin pk_ and are minted in your developer hub. Send them on every request:

Authorization: Bearer pk_your_key_here

Three separate things must all hold, and each fails differently. The key must carry the pro:read scope, chosen when you mint it. Your account must hold the pro.api_access entitlement, which comes from your plan. And for a brief specifically, the client’s consent grant for that matter must be live. A consumer portfolio key will not work here, and a key from here will not work on the consumer API.

Requests are capped per hour. The cap is your plan’s pro.api_rate_limit entitlement rather than a fixed figure, and brief fetches carry a second, independent egress cap, because a brief is a client’s personal file and bulk pulls are not an ordinary access pattern. Whichever of the two runs out first answers 429.

Endpoints

Quickstart

Four calls, in order. The last one is the case most integrations get wrong, so it is worth running deliberately before you rely on the lane.

# 1. Mint a key with the pro:read scope in your developer hub, then
#    put it in a file curl reads, NOT on the command line. Every process's argv
#    is readable by other users on the same host, so a key passed with -H leaks
#    to anyone who can run ps.
umask 077; TW_CFG=$(mktemp); trap 'rm -f "$TW_CFG"' EXIT INT TERM HUP
printf 'header = "Authorization: Bearer %s"\n' "$TW_KEY" > "$TW_CFG"

# 2. List the matters you may pull a brief for (no client data in this response)
curl -s --config "$TW_CFG" \
     https://api.thewill.ai/api/v1/pro/ext/matters/

# 3. Fetch one brief. Use an id whose brief_available was true.
curl -s --config "$TW_CFG" \
     https://api.thewill.ai/api/v1/pro/ext/matters/MATTER_ID/brief/

# 4. A lapsed or revoked grant answers 404, not 403. Handle it as "not available
#    now" and re-read brief_available, rather than treating it as a hard error.
curl -s -o /dev/null -w '%{http_code}\n' --config "$TW_CFG" \
     https://api.thewill.ai/api/v1/pro/ext/matters/MATTER_ID/brief/

The matter list

/api/v1/pro/ext/matters/ answers one question: which matters may you pull a brief for, and until when. It is deliberately free of client data, so a stolen key that only ever lists learns the shape of a caseload and nothing about the people in it.

The brief response, schema v2

A worked response, trimmed for length. The section bodies vary by matter and by the tier the client granted you.

{
  "export_id": "6f1b2e4a-9d33-4f7c-9d2e-0a6a2f1c8b04",
  "schema_version": "2.0",
  "issued_at": "2026-09-10T09:14:22Z",
  "expires_at": "2026-12-10T09:14:22Z",
  "matter_reference": "MATTER-3a7f19c8-2b40-4d6e-8a11-5f0c9e7d3b26",
  "recipient": {
    "professional_name": "A. Solicitor",
    "professional_id": "1d4c8b60-7e29-4f13-9c05-6a2b8d41e7f9",
    "firm_name": "Example Legal LLP",
    "regulatory_id": "000000",
    "professional_license": ""
  },
  "grant_id": "1c9f7d02-5b41-4a8e-8f0b-2d3f6a1e5c77",
  "handling_notice": "This pack is a copy of one client matter, prepared with that client's consent ...",
  "third_party_data_sections": [
    { "key": "wills", "title": "Will instructions", "whose_data": "Executors, beneficiaries, guardians, trustees and witnesses ..." }
  ],
  "brief": {
    "schema_version": "1.0",
    "generated_on": "2026-09-10",
    "tier": "full",
    "tier_display": "Full instructions",
    "tier_description": "The client shared their full instructions with you.",
    "next_step": "Draft from the instructions below.",
    "client_name": "J. Client",
    "approach_reference": "APPROACH-8c17",
    "sections": [
      { "key": "wills", "title": "Will instructions", "purpose": "...", "fields": [], "entries": [], "free_text": [] }
    ],
    "withheld": []
  },
  "sections": [
    {
      "key": "wills",
      "title": "Will instructions",
      "purpose": "What the client asked for",
      "disclosure": "full",
      "rows": [
        { "step": 3, "title": "Executors", "entries": [] }
      ]
    }
  ]
}

The envelope is fixed. Every field below is present on every successful response, though several may be null.

Errors

What each status means here, which is not always what it means generally. The 404 is the one to read carefully.

Versioning and deprecation

Pin on the major component of schema_version only. A minor bump adds fields and never removes or retypes one, so a client that pins 2 keeps working across additive releases, while a client that pins 2.0 breaks on one for no reason. Ignore fields you do not recognise rather than rejecting the response.

A major bump is announced before it ships, and the previous major stays served for the period stated in that announcement. Schema v1, the language-referral brief, remains served and no end date has been set for it; one will be announced in the same way if it ever is. Note that the nested brief object carries its own schema_version, which is the v1 family and is versioned independently of the envelope around it.

Generate your client from the schema

The field tables above are held to the serialisers that answer the requests by a test that fails on any drift, but the published schema is the contract. Point your generator at /api/v1/pro/ext/schema/, or browse it interactively:

Open the interactive API reference (opens in a new tab)