> 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/entity-results/retrieving-thorough-entity-ownership-structures.md).

# Retrieving thorough entity ownership structures

Once a verification has processed, you can retrieve the entity's ownership structure.

Retrieving the ownership structure of an entity is simple, and is available for manually-entered or automatically-detected directors, shareholders, universal beneficial owners, or others.

## Retrieving an entity's ownership structure

<mark style="color:green;">`POST`</mark> `/api-retrieve-ownership`

Once the entity has been verified, retrieve the ownership structure and information.

**Headers**

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

**Body**

| Name          | Type   | Description                                                                                                                                                                                                                    |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `applicantId` | string | Unique applicantId generated on entity creation <mark style="color:red;">(required)</mark>                                                                                                                                     |
| `format`      | string | Set to `standard` to wrap the response in `{"status", "response"}`, like our other endpoints. Leave it out to get the original response shape shown in the first two tabs below. <mark style="color:orange;">(optional)</mark> |

**Response**

{% hint style="info" %}
**Empty values are always `null`.** When a value isn't available, the field is returned as a JSON `null` (not the text `"null"`, an empty string, or `"Unavailable"`). Lists with no entries are returned as `[]`.
{% endhint %}

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

```json
{
  "ownershipInsight": {
    "verifiedEntity": {
      "name": "EXAMPLE HOLDINGS PTY LTD",
      "registrationNumber": "123456789",
      "totalCapital": 1000000,
      "registeredAddress": "1 Example Street, Sample City, ST, 0000"
    },
    "stakeholders": [
      {
        "applicantId": null,
        "name": "JANE EXAMPLE",
        "uboType": "Individual",
        "detectedPositions": ["UBO", "Director", "Shareholder"],
        "inputtedPosition": null,
        "address": "2 Sample Road, Sample City, ST, 0000",
        "email": "jane@example.com",
        "phone": "+61400000000",
        "registrationNumber": null,
        "sharesHeldInVerifiedEntity": [500000],
        "typeOfSharesHeldInVerifiedEntity": ["ORD"],
        "percentageOfSharesHeldInVerifiedEntity": 50.0,
        "jointHolding": false,
        "isFirstLevelStakeholder": true,
        "stakeholders": []
      },
      {
        "applicantId": "1784178339854x158496588203819001",
        "name": "PARENT HOLDINGS LTD",
        "uboType": "Company",
        "detectedPositions": ["Shareholder"],
        "inputtedPosition": "Shareholder",
        "address": "3 Corporate Ave, Sample City, ST, 0000",
        "email": null,
        "phone": null,
        "registrationNumber": "987654321",
        "sharesHeldInVerifiedEntity": [500000],
        "typeOfSharesHeldInVerifiedEntity": ["ORD"],
        "percentageOfSharesHeldInVerifiedEntity": 50.0,
        "jointHolding": false,
        "isFirstLevelStakeholder": true,
        "stakeholders": [
          {
            "name": "JOHN SAMPLE",
            "type": "Individual",
            "sharesHeldInParentEntity": [100],
            "typeOfSharesHeldInParentEntity": ["ORD"],
            "percentageOfSharesHeldInParentEntity": 100.0,
            "percentageOfSharesHeldIndirectlyInVerifiedEntity": 50.0,
            "jointHolding": false,
            "rolesHeldInParentEntity": ["Director", "Shareholder"]
          }
        ]
      }
    ]
  }
}
```

{% endtab %}

{% tab title="200 (UK entity)" %}

```json
{
  "ownershipInsight": {
    "verifiedEntity": {
      "name": "EXAMPLE TRADING LTD",
      "registrationNumber": "01234567",
      "totalCapital": null,
      "registeredAddress": "4 Example Lane, Sample Town, AB1 2CD"
    },
    "stakeholders": [
      {
        "applicantId": "1793200516074x672617903315113001",
        "name": "SMITH, Jane Example",
        "uboType": "Individual",
        "detectedPositions": ["director", "UBO"],
        "inputtedPosition": null,
        "address": "4 Example Lane, Sample Town, AB1 2CD",
        "email": null,
        "phone": null,
        "registrationNumber": null,
        "sharesHeldInVerifiedEntity": [],
        "typeOfSharesHeldInVerifiedEntity": [],
        "percentageOfSharesHeldInVerifiedEntity": null,
        "ownershipBand": "75-100%",
        "natureOfControl": "Ownership of shares 75 to 100 percent, Right to appoint and remove directors",
        "isFirstLevelStakeholder": true,
        "stakeholders": []
      }
    ]
  }
}
```

{% endtab %}

{% tab title="200 (format=standard)" %}

```json
{
  "status": "success",
  "response": {
    "ownershipInsight": {
      "verifiedEntity": {
        "name": "EXAMPLE HOLDINGS PTY LTD",
        "registrationNumber": "123456789",
        "totalCapital": 1000000,
        "registeredAddress": "1 Example Street, Sample City, ST, 0000"
      },
      "stakeholders": [ ... ]
    }
  }
}
```

{% endtab %}

{% tab title="200 - Not found" %}
Without `format`:

```json
{
  "response": "No entity found"
}
```

With `format=standard`:

```json
{
  "status": "error",
  "response": "No entity found"
}
```

`response` is `"No entity found"` when the `applicantId` doesn't match an entity, and `"No ownership found"` when the entity exists but has no ownership data yet.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Use `format=standard` for new integrations.** It returns `"status": "success"` or `"status": "error"` in the body, so you can check every response the same way. Errors are returned with HTTP status 200, so check `status`, not just the HTTP code.
{% endhint %}

`detectedPositions` types are roles that we've automatically identified during verification.

`inputtedPosition` types are roles that the entity has manually entered, in the event of manual fallback.

{% hint style="info" %}
Note: The `applicantId` is `null` when the representative has been identified, but not yet verified. If applicable, once an applicant or entity has been created to verify the representative, manually or automatically in a flow, the `applicantId` will appear.
{% endhint %}

{% hint style="info" %}
**Walking the full ownership tree.** The top-level `stakeholders[]` is the whole ownership tree flattened into one list, at any depth. Companies further down the chain appear there too, with `isFirstLevelStakeholder: false`, their own `registrationNumber`, and their own direct holders in a nested `stakeholders[]`. Nested entries never contain a further `stakeholders` array, and don't carry `registrationNumber` or `address`. To rebuild deeper levels, match each nested `name` to the top-level entry with the same name, and repeat. This goes as deep as the registry data allows.

Every holder and officeholder found is returned, whatever UBO threshold your flow uses. The `UBO` value in `detectedPositions` follows the registry's beneficial-owner rule (25%), so apply your own threshold with `percentageOfSharesHeldInVerifiedEntity` if it differs.
{% endhint %}

{% hint style="info" %}
**UK entities.** Companies House doesn't publish share numbers for persons with significant control (PSCs), only a band. For these stakeholders `percentageOfSharesHeldInVerifiedEntity` is `null`, the band is in `ownershipBand`, and the full wording is in `natureOfControl`. A person who is both a director and a PSC appears once, with both roles in `detectedPositions`. Resigned officers and ceased PSCs aren't included. Names are returned as Companies House lists them, usually `SURNAME, Given names`. `jointHolding` and indirect percentages are calculated for Australian entities only.
{% endhint %}

### Response properties

With `format=standard`, the properties below sit inside `response`.

| Property           | Type   | Description                                                                               |
| ------------------ | ------ | ----------------------------------------------------------------------------------------- |
| `ownershipInsight` | object | Single wrapper object containing the entity being verified and its full stakeholder tree. |

| Property             | Type           | Description                                                                                                                      |
| -------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `verifiedEntity`     | object         | The company that was verified (the root of the ownership tree).                                                                  |
| `name`               | string \| null | Legal entity name.                                                                                                               |
| `registrationNumber` | string \| null | Company registration number. Always a string, even though it's numeric (e.g. `"`<mark style="color:red;">`654135430`</mark>`"`). |
| `totalCapital`       | number \| null | The entity's total issued capital, as a number. `null` when the registry doesn't provide it.                                     |
| `registeredAddress`  | string \| null | Full address as a single unstructured string, not split into fields.                                                             |

| Property                                 | Type           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `stakeholders[]`                         | array          | Every company and individual found in the verified entity's ownership tree, at any depth, as one flat list. Individuals and companies are mixed in the same array, distinguished by <mark style="color:red;">`uboType`</mark>. Companies below the first level are included with <mark style="color:red;">`isFirstLevelStakeholder: false`</mark>. Each entry lists only its own direct holders in its nested <mark style="color:red;">`stakeholders[]`</mark>, and nested entries don't contain a further <mark style="color:red;">`stakeholders`</mark> array. A stakeholder normally appears once, but the same person can occasionally appear twice under different spellings of their name. Stakeholders removed from the entity aren't included. |
| `applicantId`                            | string \| null | The unique ID of the <mark style="color:red;">verified</mark> applicant or entity. `null` until the stakeholder has been created for verification.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `name`                                   | string         | Individual's full name (first and last name) or company name. For UK entities, names are returned as the registry lists them, usually <mark style="color:red;">`SURNAME, Given names`</mark>.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `uboType`                                | string         | `"`<mark style="color:red;">`Individual`</mark>`"` \| `"`<mark style="color:red;">`Company`</mark>`"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `detectedPositions`                      | array\<string> | Roles that we've automatically identified during verification. Can be <mark style="color:red;">`[]`</mark> (e.g. historical registry entries with no current role). Example values: <mark style="color:red;">`Director`</mark>, <mark style="color:red;">`Secretary`</mark>, <mark style="color:red;">`Shareholder`</mark>, <mark style="color:red;">`Managing Director`</mark>, <mark style="color:red;">`UBO`</mark>. Casing follows the source registry (UK roles are lowercase, e.g. <mark style="color:red;">`director`</mark>).                                                                                                                                                                                                                  |
| `inputtedPosition`                       | string \| null | Role that the entity has manually entered. `null` if none was entered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `address`                                | string \| null | Full address string. `null` when unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `email`                                  | string \| null | Email address, when one was captured (for example on the manual owner form). `null` otherwise, including most automatically discovered owners.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `phone`                                  | string \| null | Phone number, when one was captured. `null` otherwise.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `registrationNumber`                     | string \| null | Registration number (as a string) for companies. `null` for individuals or when unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `sharesHeldInVerifiedEntity`             | array\<float>  | The number of shares the stakeholder holds directly in the verified entity, one entry per share class. Can be <mark style="color:red;">`[]`</mark>, for example when the stakeholder only holds shares through another company. Length matches <mark style="color:red;">`typeOfSharesHeldInVerifiedEntity`</mark>                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `typeOfSharesHeldInVerifiedEntity`       | array\<string> | Share class labels, positionally matched to <mark style="color:red;">`sharesHeldInVerifiedEntity`</mark>. Example values: <mark style="color:red;">`"A"`</mark>, <mark style="color:red;">`"B"`</mark>, <mark style="color:red;">`"ORD"`</mark>, <mark style="color:red;">`"Direct"`</mark> — varies by jurisdiction/source.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `percentageOfSharesHeldInVerifiedEntity` | float \| null  | Effective (look-through) ownership % in the verified entity: shares held directly, plus shares held through companies further up the chain. When <mark style="color:red;">`sharesHeldInVerifiedEntity`</mark> is empty, the percentage is entirely indirect. `null` when there's no exact share figure (for example a UK PSC, which has a band instead; see `ownershipBand`). Owners removed from the entity aren't counted in the total.                                                                                                                                                                                                                                                                                                              |
| `ownershipBand`                          | string \| null | **Non-Australian entities only; not returned for Australian entities.** The ownership band from the registry, for registries that publish a band instead of share numbers (UK Companies House PSCs). One of <mark style="color:red;">`"25-50%"`</mark>, <mark style="color:red;">`"50-75%"`</mark>, <mark style="color:red;">`"75-100%"`</mark>. `null` when there's no band.                                                                                                                                                                                                                                                                                                                                                                          |
| `natureOfControl`                        | string \| null | **Non-Australian entities only; not returned for Australian entities.** The registry's full nature-of-control wording, e.g. <mark style="color:red;">`"Ownership of shares 75 to 100 percent, Voting rights 75 to 100 percent, Right to appoint and remove directors"`</mark>. `null` when the registry doesn't provide it.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `jointHolding`                           | boolean        | **Australian entities only.** Marks whether this stakeholder shares legal title to the same block of shares with other sibling stakeholders.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `isFirstLevelStakeholder`                | boolean        | `true` when the stakeholder is a direct stakeholder of the verified entity. `false` for stakeholders further down the ownership chain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `stakeholders`                           | array\<object> | The stakeholder's own direct holders and officeholders. <mark style="color:red;">`[]`</mark> for individuals; populated for companies that themselves have traceable owners/officers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

| Property                                           | Type           | Description                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stakeholders[].stakeholders[]`                    | array          | When a stakeholder is a <mark style="color:red;">`Company`</mark>, this array unpacks *its* shareholders, directors, and other roleholders (the next layer of the ownership chain). Nested entries don't include `registrationNumber`, `address` or a further `stakeholders` array: find the company's top-level entry by `name` for those. Some stakeholders may appear multiple times if they hold stakes in multiple entities. |
| `name`                                             | string         | Name of the person/entity holding a stake in the parent stakeholder.                                                                                                                                                                                                                                                                                                                                                              |
| `type`                                             | string         | `"`<mark style="color:red;">`Individual`</mark>`"` \| `"`<mark style="color:red;">`Company`</mark>`"`.                                                                                                                                                                                                                                                                                                                            |
| `sharesHeldInParentEntity`                         | array\<float>  | Shares held in the ***parent stakeholder***, not the originally verified entity. Can be <mark style="color:red;">`[]`</mark> (e.g. for a Director/Managing Director with no shareholding).                                                                                                                                                                                                                                        |
| `typeOfSharesHeldInParentEntity`                   | array\<string> | Positionally matched to <mark style="color:red;">`sharesHeldInParentEntity`</mark>.                                                                                                                                                                                                                                                                                                                                               |
| `percentageOfSharesHeldInParentEntity`             | float \| null  | % owned of the parent stakeholder.                                                                                                                                                                                                                                                                                                                                                                                                |
| `percentageOfSharesHeldIndirectlyInVerifiedEntity` | float \| null  | **Australian entities only.** Calculated indirect % ownership of the ***original verified entity***, flowed down through the parent.                                                                                                                                                                                                                                                                                              |
| `jointHolding`                                     | boolean        | **Australian entities only.** Marks whether this stakeholder shares legal title to the same block of shares with other sibling stakeholders.                                                                                                                                                                                                                                                                                      |
| `rolesHeldInParentEntity`                          | array\<string> | Roles held in the parent stakeholder. Example values: <mark style="color:red;">`Director`</mark>, <mark style="color:red;">`Secretary`</mark>, <mark style="color:red;">`Shareholder`</mark>, <mark style="color:red;">`Managing Director`</mark>.                                                                                                                                                                                |


---

# 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/entity-results/retrieving-thorough-entity-ownership-structures.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.
