Trust deed analysis | Admiin API

Before you begin

You need an access token and your partner id. See Authentication and first request.

POST /v1/business-lookups resolves company ownership from the public registers. For a trust it returns nothing useful, which is why the manual verification path exists. Deed analysis is the missing input to it.

1. Create the analysis

Creating an analysis returns the job and a signed upload that is valid for 15 minutes.

POST /v1/deed-analyses
X-Partner-Id: YOUR_PARTNER_ID

{ "verificationRequestId": "optional" }

{
  "deedAnalysis": { "id": "3f0c…", "status": "AWAITING_UPLOAD" },
  "upload": {
    "url": "https://…",
    "headers": {
      "Content-Type": "application/pdf",
      "<additional signed header>": "<value>"
    },
    "expiresAt": "2026-08-06T04:27:09.000Z"
  }
}

2. Upload the deed

Send exactly the headers we returned, with exactly those values. Do not build your own set and do not omit any entry. Those headers are part of the signed upload, so any drift produces a 403.

PUT <upload.url>
<every upload.headers entry, exactly as returned>

<the PDF bytes>

In a browser, send the File or Blob directly as the request body. Do not wrap it in FormData, encode it as JSON or add your partner API Authorization header. The signed URL authenticates this S3 request.

const response = await fetch(upload.url, {
  method: 'PUT',
  headers: upload.headers,
  body: pdfFile,
  credentials: 'omit',
});

if (!response.ok) {
  throw new Error(`PDF upload failed (${response.status})`);
}
// Start the analysis only after the upload succeeds.

The upload bucket permits cross-origin PUT requests from partner sites and localhost with the returned headers. A valid signed URL is still required; the bucket is private. If the browser's OPTIONS preflight fails, contact Admiin with the Origin request header and request time. Do not use mode: 'no-cors' or modify the signed URL's query parameters. Upload before upload.expiresAt; an expired URL cannot be reused.

3. Start the analysis

POST /v1/deed-analyses/{id}/start

The file is validated here, not at upload. A presigned PUT cannot enforce a size or a content type, so nothing about the file is trusted until this call. The limits are 25 MB and 150 pages, and it must be a real PDF.

All four rejections leave the analysis AWAITING_UPLOAD, so you can fix the file and upload again against the same id rather than starting over.

`code`	What to do
`UPLOAD_NOT_FOUND`	The `PUT` did not land, or the window lapsed. Upload and retry.
`FILE_TOO_LARGE`	Over 25 MB.
`NOT_A_PDF`	Not a PDF, or one that will not parse.
`TOO_MANY_PAGES`	Over 150 pages. Split it and analyse the parts.

Reading the result

Extracted parties are sent once in the deed-analysis.completed webhook. Save the payload when it arrives; the parties cannot be fetched or re-sent.

Field	What it contains
`parties`	People and businesses with their role, kind and confidence.
`sourcePage`, `sourceQuote`	The deed evidence supporting each extracted party.
`acn`, `abn`	Digits-only, check-digit validated values for business parties. They are copied from the deed, not verified against ASIC or the ABR.
`address.full`	The address as printed in the deed. It is not parsed or normalised.
`beneficiaryClasses`	Beneficiary classes named by the deed, without inferring individual beneficiaries.
`trust`	Trust name, ABN, type, jurisdiction and dates as printed. It is `null` when the deed does not name the trust.

Date of birth is not returned. Collect it from the individual during verification.

{
  "type": "deed-analysis.completed",
  "trust": {
    "name": "The Everton Family Trust",
    "abn": "51824753556",
    "trustType": "DISCRETIONARY",
    "jurisdiction": "New South Wales",
    "establishedDate": "14 March 2018",
    "vestingDate": null
  },
  "parties": [
    {
      "role": "TRUSTEE",
      "partyKind": "BUSINESS",
      "businessName": "Northstar Parakeet Services Pty Ltd",
      "acn": "000000019",
      "abn": null,
      "address": { "full": "Level 12, 101 Compass Arcade, Glasshouse Fern QLD 4997" },
      "confidence": "HIGH",
      "sourcePage": 2,
      "sourceQuote": "Trustee: Northstar Parakeet Services Pty Ltd ACN 000 000 019"
    },
    {
      "role": "APPOINTOR",
      "partyKind": "INDIVIDUAL",
      "firstName": "Lydia",
      "lastName": "Everton",
      "acn": null,
      "abn": null,
      "address": { "full": "6 Banksia Mews, Harbour Wattle NSW 2058" },
      "confidence": "HIGH",
      "sourcePage": 2,
      "sourceQuote": "Appointor / Principal Lydia Everton 6 Banksia Mews, Harbour Wattle NSW 2058"
    }
  ]
}

GET /v1/deed-analyses/{id} gives you status and counts but never names. Use partyCount to confirm the webhook covered everything. If you poll it as a fallback, stop at REVIEW_READY, FAILED, DISCARDED or EXPIRED.

role uses the same vocabulary as a verification individual, so an extracted party goes straight to POST /v1/verifications/{id}/individuals with no remapping. Every value Deed Analysis returns — TRUSTEE, APPOINTOR, BENEFICIARY, SETTLOR, PROTECTOR_GUARDIAN, UBO and OTHER_CONTROLLER — is accepted there. Names are not: we never take end-user names, so send externalId and let the individual supply their own details during verification.

Failures

On failure you get deed-analysis.failed with a failureReason. None of these are billed. Only a completed analysis is.

`failureReason`	Retry?
`OCR_FAILED`	Often a scan-quality problem. A cleaner copy may work.
`TFN_CONTENT_DETECTED`	No. See tax file number content below.
`EXTRACTION_INVALID_OUTPUT`	Retrying rarely helps. The document is usually atypical.
`ANALYSIS_UNAVAILABLE`	Yes, later.
`TIMED_OUT`	Yes.

If a deed appears to contain tax file number content, the analysis stops. The document is quarantined and permanently deleted, no parties are extracted, and the failure tells you what happened without echoing any of it. Remove the affected pages and upload again.

Retention and deletion

Item	Longest period	Notes
Upload URL	15 minutes	The URL stops accepting uploads.
Deed and extracted working text	Up to 7 days	Deleted earlier when analysis completes, fails or is discarded. Unstarted uploads are normally removed within 2 hours. `documentPurgedAt` records the deletion.
Temporary processing results	Up to 7 days	Not available through this API.
Webhook payload	About 33 hours	Retained for delivery retries, then scheduled for deletion.
Job record	No automatic expiry	Contains operational identifiers, status, counts, flags and timestamps. It does not contain deed text, extracted names, addresses or the uploaded filename.

Once a webhook is delivered, you are responsible for retaining or deleting your copy under your own legal and operational requirements.

Discarding an analysis

DELETE /v1/deed-analyses/{id}

This destroys the documents and marks the analysis DISCARDED, keeping the job record so you retain evidence it existed and any charge stays reconcilable. Use it when the wrong deed was uploaded, the request was withdrawn, or the analysis no longer has a valid business purpose.

It is most useful before starting analysis: completed and failed analyses have already had their document content purged. Discarding does not recall a webhook that was already delivered, and it does not reverse an existing charge.