Entity organigram (ownership structure)

The organigram is eFICA's ownership structure tree. It models who owns the entity — individuals, trusts, and other corporate entities — with shareholding percentages at each level.

This guide explains the organigram for business analysts (what to capture) and developers (how to submit it via the API).

When is an organigram required?

Check showOrganigram on the entity type from GET /api/v1/settings/entity-types:

`showOrganigram`	Integration path
`false`	Flat directors/members list — no organigram endpoints (see UBOs)
`true`	Build organigram → verify organigram → per-person UBO loop → `shareholding-confirm` — this guide

What the organigram represents (business view)

Think of the organigram as a family tree of ownership:

Root (the entity being onboarded)
├── Individual shareholder (25%)
├── Trust shareholder (25%)
│   ├── Trust member — Founder
│   └── Trust member — Trustee
└── Individual shareholder (50%)

Business rules your integration should enforce:

Percentages at each level should reflect the client's declared ownership.
When the organigram is complete, call verify organigram before reviewing individuals.
Every natural person in the tree (UBO individuals and trust members) must complete the same three-step process as the non-organigram path: update → PEP confirm → document confirm.
You cannot add more UBOs after the organigram has been verified.
Trust shareholders require related parties (founders, trustees, beneficiaries, etc.) with relationship types from settings.
Complex structures (many layers or nodes) can increase the entity's risk rating.

Node types

`shareholderType`	Meaning
`Root`	The entity being onboarded — must be the first element of the `entityOrganigram` array
`Individual`	A natural person (director, shareholder, or trust member)
`Trust`	A trust that holds shares in the entity
`Entity`	Another corporate entity that holds shares

Workflow summary

Building the organigram

Capture the full ownership tree — individuals, corporate entities, and trusts — with share percentages at each level.

Supported integration approach: build and maintain the complete entityOrganigram JSON in your system (draft saves as needed), then submit the full tree in one call via verify organigram below.

Verify organigram (Mandatory)

Endpoint: PATCH /api/v1/entity/:id/verify-organigram

Call this when the organigram structure is complete. eFICA will:

Create or update trust records (ficaEntityTrust)
Create or update UBO records (match existing UBOs by uboID UUID; null creates new)
Link trust related parties with trustRelatedPartyTypes
Finalise the ownership structure
Return the processed organigram with eFICA UUIDs backfilled

After verify, no more UBOs can be added. Proceed to the per-person UBO loop in UBOs.

note

After the organigram is verified, incremental node changes are rejected ("organigram has already been finalised").

Bulk request structure

The request body contains entityOrganigram — a JSON array whose first element must be the Root node.

Example request

{
  "entityOrganigram": [
    {
      "guid": "58a7eede-4a4c-421e-bfcc-d4a05b6770e5",
      "shareholderType": "Root",
      "shareholderEntityName": "Example Gaming (Pty) Ltd",
      "uboPercentage": 100,
      "shareholderPercentage": 100,
      "children": [
        {
          "guid": "d02d8786-2845-4bd6-b99a-180015b9cfd8",
          "shareholderType": "Trust",
          "shareholderTrustName": "Family Trust",
          "shareholderPercentage": 25,
          "uboPercentage": 25,
          "parentGUID": "58a7eede-4a4c-421e-bfcc-d4a05b6770e5",
          "children": [
            {
              "guid": "e05cb316-da27-4cff-b93e-03e01f5e1663",
              "uboID": null,
              "firstName": "John",
              "lastName": "Doe",
              "shareholderType": "Individual",
              "shareholderPercentage": 0,
              "uboPercentage": 0,
              "isTrustMember": true,
              "isDirector": true,
              "hasResolution": "false",
              "parentGUID": "d02d8786-2845-4bd6-b99a-180015b9cfd8",
              "trustRelatedPartyTypes": "[{\"id\":1,\"name\":\"Founder\"},{\"id\":3,\"name\":\"Named Beneficiaries\"}]",
              "children": []
            }
          ]
        },
        {
          "guid": "d184b90a-2cdb-4fe3-b4cf-861fd99aafc5",
          "uboID": null,
          "firstName": "Jane",
          "lastName": "Doe",
          "shareholderType": "Individual",
          "shareholderPercentage": 75,
          "uboPercentage": 75,
          "isDirector": false,
          "hasResolution": "false",
          "parentGUID": "58a7eede-4a4c-421e-bfcc-d4a05b6770e5",
          "children": []
        }
      ],
      "ubos": [],
      "trustUbos": []
    }
  ]
}

Key fields

Field	Applies to	Description
`guid`	All nodes (request)	Your stable UUID for the node
`parentGUID`	Child nodes	UUID of the parent node
`uboID`	Individual	Existing UBO UUID to update; `null` to create new
`shareholderPercentage`	All	Shareholding % at this tree level
`uboPercentage`	All	Effective UBO percentage
`trustRelatedPartyTypes`	Individual under Trust	JSON string (not raw array) of relationship types
`ubos` / `trustUbos`	Root	Summary lists — eFICA rebuilds these from the database after processing

For each Individual node that is a direct child of a Trust node, include trustRelatedPartyTypes as a stringified JSON array:

"[{\"id\":1,\"name\":\"Founder\"},{\"id\":2,\"name\":\"Trustees\"}]"

Lookup valid id and name pairs from GET /api/v1/settings/trust-related-party-types.

Do not send a raw JSON array — the value must be a string (same format the eFICA UI uses).

Response shape

After successful verify, the response uses different field names:

Request field	Response field
`guid`	`id`
`parentGUID`	`parentID`
`uboID` (on Individual)	`uboID` (eFICA UBO UUID)
Trust node `guid`	`trustID`

Example response (abbreviated):

{
  "entityOrganigram": [
    {
      "id": "58a7eede-4a4c-421e-bfcc-d4a05b6770e5",
      "shareholderType": "Root",
      "shareholderEntityName": "Example Gaming (Pty) Ltd",
      "riskStatus": "High Risk",
      "children": [ ... ],
      "ubos": [
        {
          "uboID": "e05cb316-da27-4cff-b93e-03e01f5e1663",
          "firstName": "John",
          "lastName": "Doe",
          "shareholderPercentage": 75,
          "verified": false
        },
        {
          "uboID": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "firstName": "Jane",
          "lastName": "Doe",
          "shareholderPercentage": 75,
          "verified": false
        }
      ]
    }
  ],
  "riskStatus": "High Risk",
  "riskDescription": "The entities risk score (19) equals or exceeds the high risk threshold score (15)."
}

Store each returned uboID for the per-UBO workflow in UBOs.

Risk and organigram complexity

Entity risk is recalculated when the organigram is verified or confirmed. Factors include:

Total number of nodes in the ownership tree
Partner risk threshold settings
UBO and trust-related-party counts

Entity risk may be updated on verify; the final riskStatus used for entity document requirements is returned from shareholding-confirm after all individuals are complete.

After organigram verification

Per-person UBO loop — for every UBO individual and trust individual: director-ubo-update (not ubo-create) → PEP confirm → upload all required documents → ubo-doc-confirm (UBOs guide). Repeat for each person.
Shareholding confirm — PATCH shareholding-confirm on the entity (Workflow guide). Same step as the non-organigram path.
Entity documents — upload all required entity documents (entity-doc per file), then entity-doc-confirm once, only after step 2 (Documents guide).
Onboarding decision — final approve/decline/refer (Workflow guide).

Common errors

Error	Cause
`entityOrganigram must be an array whose first node is the Root`	Missing Root node or wrong array structure
`Organigram has already been finalised`	Attempting node changes after confirm
Missing trust relationship types	Individual under Trust without `trustRelatedPartyTypes`

Workflow — full step sequence
Identifiers — UUID reference for nodes and UBOs

Document history

Version	Date	Notes
1.0	2026-06-08	Initial release

Support

For technical support and questions:

Email: melissa@efica.co.za
Melissa will co-ordinate with the development team.

This documentation is maintained by the eFICA development team. For updates and corrections, please contact your account manager.

Last Updated: 8 June 2026

When is an organigram required?​

What the organigram represents (business view)​

Node types​

Workflow summary​

Building the organigram​

Verify organigram (Mandatory)​

Bulk request structure​

Example request​

Key fields​

Trust related-party types​

Response shape​

Risk and organigram complexity​

After organigram verification​

Common errors​

Related​

Document history​

Support​