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

POST /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 (required)

Response

200

{
  "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",
        "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",
        "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"]
          }
        ]
      }
    ]
  }
}

400

{
    "statusCode": 400,
    "message": "Error: incorrect applicantId provided"
}

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.

Note: The applicantId can be empty/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.

Response properties

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	Legal entity name.
registrationNumber	string	Company registration number. Always a string, even though it's numeric (e.g. "654135430").
totalCapital	float	The entity's capital.
registeredAddress	string	Full address as a single unstructured string, not split into fields.

Property	Type	Description
stakeholders[]	array	Every direct or indirect stakeholder of the verified entity — individuals and companies mixed in the same array, distinguished by uboType. Every stakeholder is unique (no two instances of the same stakeholder appear inside this array and it is capped at 2 levels — nested stakeholders[] entries do not themselves contain a further stakeholders array)
applicantId	string	The unique ID of the verified applicant.
name	string	Individual's full name or company name.
uboType	string	"Individual" | "Company".
detectedPositions	array<string>	Roles that we've automatically identified during verification. Can be [] (e.g. historical registry entries with no current role). Example values: Director, Secretary, Shareholder, Managing Director.
inputedPosition	string	Role that the entity has manually entered.
address	string	Full address string. Can be "" (empty) when unavailable
registrationNumber	string	"null" for individuals; actual registration number (as string) for companies.
sharesHeldInVerifiedEntity	array<float>	The number of shares the stakeholder holds in the verified entity, one entry per share class. Can be []. Length matches typeOfSharesHeldInVerifiedEntity
typeOfSharesHeldInVerifiedEntity	array<string>	Share class labels, positionally matched to sharesHeldInVerifiedEntity. Example values: "A", "B", "ORD", "Direct" — varies by jurisdiction/source.
percentageOfSharesHeldInVerifiedEntity	float	Direct ownership % in verified entity.
jointHolding	boolean	Marks whether this stakeholder shares legal title to the same block of shares with other sibling stakeholders.
isFirstLevelStakeholder	boolean	Marks whether the stakeholder is a direct stakeholder of the verified entity.
stakeholders	array<object>	Nested stakeholders chain. [] for individuals; populated for companies that themselves have traceable owners/officers.

Property	Type	Description
stakeholders[].stakeholders[]	array	When a first-level stakeholder is a Company, this array unpacks its shareholders, directors, and other roleholders (i.e. the next layer up/down the ownership chain). 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	"Individual" | "Company".
sharesHeldInParentEntity	array<float>	Shares held in the parent stakeholder, not the originally verified entity. Can be [] (e.g. for a Director/Managing Director with no shareholding).
typeOfSharesHeldInParentEntity	array<string>	Positionally matched to sharesHeldInParentEntity.
percentageOfSharesHeldInParentEntity	float	% owned of the parent stakeholder.
percentageOfSharesHeldIndirectlyInVerifiedEntity	float	Calculated indirect % ownership of the original verified entity, flowed down through the parent. Available only for AU verified entities.
jointHolding	boolean	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: Director, Secretary, Shareholder, Managing Director.