> For the complete documentation index, see [llms.txt](https://manual.personr.co/api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.personr.co/api-documentation/entities/uploading-documents-to-an-entity/analysing-a-trust-deed.md).

# Analysing a trust deed

For trusts and superannuation funds, upload the trust deed and ask us to extract the trustees, appointors and beneficiaries.

Trusts and superannuation funds don't list their owners on a public registry, so an entity check returns `deedRequired: true` and no ownership. To find the owners, upload the trust deed and call this endpoint. We read the deed, add the trustees, appointors and beneficiaries to the entity's ownership, and notify you by webhook when it's done.

The whole process works through the API:

1. Create the entity with its 11-digit ABN using [Creating an entity](https://manual.personr.co/api-documentation/entities/creating-an-entity.md).
2. Upload the deed with [Uploading documents to an entity](https://manual.personr.co/api-documentation/entities/uploading-documents-to-an-entity.md), using `docSubType` `TRUST_AGREEMENT`.
3. Call this endpoint with the entity's `applicantId` as `entityId`.

{% hint style="warning" %}
Uploading the deed doesn't start the analysis on its own. You need to call this endpoint.
{% endhint %}

***

## Start the deed analysis

<mark style="color:green;">`POST`</mark> `/api-extract-trust-deed-info`

Start extracting owners from the trust deed uploaded to an entity.

| Name          | Value                                       |
| ------------- | ------------------------------------------- |
| Content-Type  | `multipart/form-data` or `application/json` |
| Authorization | `Bearer YOUR_TOKEN`                         |

**Body**

| Name       | Type   | Description                                                             |
| ---------- | ------ | ----------------------------------------------------------------------- |
| `entityId` | string | The entity's `applicantId`, returned when you created it **(required)** |

#### Request

{% tabs %}
{% tab title="cURL" %}

```sh
curl -X POST https://enterprise.personr.co/api/1.1/wf/api-extract-trust-deed-info \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -F "entityId=4242424242424x424242424242424242"
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://enterprise.personr.co/api/1.1/wf/api-extract-trust-deed-info", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN"
  },
  body: JSON.stringify({ entityId: "4242424242424x424242424242424242" })
});

console.log(await response.json());
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.post(
    "https://enterprise.personr.co/api/1.1/wf/api-extract-trust-deed-info",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"entityId": "4242424242424x424242424242424242"},
)

print(response.json())
```

{% endtab %}
{% endtabs %}

**Response**

A successful call means the analysis has started, not that it has finished. Errors return `response: "error"` with a `statusCode` and `errorMessage` (both sent as text).

{% tabs %}
{% tab title="200 - Started" %}

```json
{
    "status": "success",
    "response": {
        "response": "success"
    }
}
```

{% endtab %}

{% tab title="Errors" %}

```json
{
    "status": "success",
    "response": {
        "statusCode": "404",
        "response": "error",
        "errorMessage": "No trust agreement associated with this entity was found. Please upload one before verifying the entity."
    }
}
```

{% endtab %}
{% endtabs %}

| `statusCode` | `errorMessage`                                                                                           | What to do                                                                   |
| ------------ | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `404`        | Entity not found                                                                                         | Check the `entityId`. Entities in another workspace also return this.        |
| `403`        | You don't have access to this entity                                                                     | Use a token for the workspace that owns the entity.                          |
| `404`        | Entity is not a trust or superfund                                                                       | Deed analysis is only for trusts and superannuation funds.                   |
| `404`        | No trust agreement associated with this entity was found. Please upload one before verifying the entity. | Upload the deed with `docSubType` `TRUST_AGREEMENT`, then call again.        |
| `400`        | Trust information extraction was already requested                                                       | The analysis has already been started for this entity. Wait for the webhook. |
| `400`        | Trust information was already extracted.                                                                 | The deed has already been analysed. Retrieve the ownership instead.          |

{% hint style="info" %}
Each entity's deed can be analysed through the API once. If you need to analyse a different deed for the same entity, contact us.
{% endhint %}

***

## What happens next

The analysis usually takes a few minutes. When it finishes:

* The trustees, appointors and beneficiaries are added to the entity. Retrieve them with [Retrieving entity ownership structures](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-ownership-structures.md) or [Retrieving thorough entity ownership structures](https://manual.personr.co/api-documentation/entity-results/retrieving-thorough-entity-ownership-structures.md).
* `deedRequired` becomes `false` and `trustDeedStatus` shows the deed's status in [Retrieving entity verification results](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-verification-results.md).
* If you've turned on the [Ownership ready webhook](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-verification-results/setting-up-a-webhook/ownership-ready-webhook.md), it fires once the owners have been added.
* We also send an `entity.deed_ready` webhook to your webhook URL.

### Example: owners from a deed

Owners found in a deed come back in the ownership endpoints alongside any registry owners. Their `detectedPosition` shows their role under the deed (for example Trustee, Member, Appointor or Beneficiary), plus `UBO` when they meet the beneficial ownership test. Deeds don't record shareholdings or addresses, so those fields are empty.

A [Retrieving entity ownership structures](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-ownership-structures.md) response for a self-managed super fund with two individual trustees who are also its members:

```json
{
    "ubos": [
        {
            "parentEntity": "4242424242424x424242424242424242",
            "applicantId": "null",
            "uboType": "Individual",
            "name": "Jane Example Citizen",
            "detectedPosition": ["Member and Trustee", "UBO"],
            "inputtedPosition": "null",
            "address": "null",
            "registrationNumber": "null",
            "shares": [],
            "shareClass": []
        },
        {
            "parentEntity": "4242424242424x424242424242424242",
            "applicantId": "null",
            "uboType": "Individual",
            "name": "John Example Citizen",
            "detectedPosition": ["Member and Trustee", "UBO"],
            "inputtedPosition": "null",
            "address": "null",
            "registrationNumber": "null",
            "shares": [],
            "shareClass": []
        }
    ]
}
```

Verify each owner's identity as you would for registry owners.

### `entity.deed_ready` webhook

```json
{
    "applicantId": "4242424242424x424242424242424242",
    "event": "entity.deed_ready",
    "trustDeedStatus": "extracted",
    "deedRequired": "false",
    "ownershipCount": "2",
    "sourceKey": "your-reference",
    "externalUserId": "[\"your-id\"]",
    "sentAt": "2026-11-09T02:15:00.000Z"
}
```

| Field             | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| `applicantId`     | The entity's `applicantId`.                                     |
| `event`           | Always `entity.deed_ready`.                                     |
| `trustDeedStatus` | `extracted` once the analysis has finished.                     |
| `deedRequired`    | `"true"` or `"false"`, as text.                                 |
| `ownershipCount`  | How many owners were added from the deed.                       |
| `sourceKey`       | The `sourceKey` you sent when creating the entity, if any.      |
| `externalUserId`  | Your external IDs for the entity, as a JSON-style list in text. |
| `sentAt`          | When the webhook was sent (ISO 8601, UTC).                      |

It uses the same webhook URL and bearer key as your other entity webhooks. Treat it as a notification and fetch the ownership endpoint for the full details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://manual.personr.co/api-documentation/entities/uploading-documents-to-an-entity/analysing-a-trust-deed.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
