Ultimate beneficial owners (UBOs)

A UBO is any natural person linked to an entity FICA record: director, shareholder, trust member, or trust related party. Each UBO must complete their own compliance steps before the entity can be onboarded.

This page covers creating, updating, and completing UBOs via the Public API.

UBO sources

How a UBO record first appears depends on entity type and create path:

Source	When	What you receive
CIPC pre-create	Entity create for SA companies (`foreignEntityType: false`)	`createdUbos[]` with `uboUUID`
Manual create	`POST .../ubo-create` — only when `showOrganigram` is `false`	`uboUUID` in response
Organigram verify	`PATCH .../verify-organigram` — only when `showOrganigram` is `true`	`uboID` (UBO UUID) on each Individual node in response

Store every UBO UUID — you need it for all per-person endpoints.

ubo-create is not available on the organigram path

When showOrganigram is true, all UBO and trust-member records are created by verify-organigram. Do not call POST .../ubo-create. After verify, you also cannot add more UBOs.

Per-UBO workflow

Repeat for every UBO and trust individual. Steps 2–4 are the same on both paths; step 1 differs by showOrganigram.

`showOrganigram`	Before the UBO loop	Step 1 — how to get/update the person
`false`	View directors/members; add or edit on a flat list	`POST .../ubo-create` for new people, or `PATCH .../director-ubo-update` for existing
`true`	Build and verify the organigram first	`PATCH .../director-ubo-update` only — UBOs already exist from verify

Step	Action	Endpoint
1	Update UBO — complete personal data for an existing record	`PATCH .../director-ubo-update`
1b	Add new UBO — only when `showOrganigram` is `false`	`POST .../ubo-create`
2	PEP confirm — record PEP and sanctions review	`PATCH .../ubo-pep-confirm`
3	Upload documents — one file per call, as many calls as needed	`POST .../ubo-doc-upload`
4	Confirm documents — only when every required document is uploaded	`PATCH .../ubo-doc-confirm`

Only when all UBOs and trust individuals have completed steps 1–4 should you call PATCH shareholding-confirm on the entity. Entity document upload comes after that — see Workflow.

Document requirements come from individual-docs after step 2 — see Documents.

Create a director or UBO

Endpoint: POST /api/v1/entity/:id/ubo-create

Available only when showOrganigram is false.

Path parameter: :id = entity UUID

Use to add a person who does not already have a UBO record (e.g. an extra shareholder not returned from CIPC, or a foreign entity with no CIPC pre-create). For existing records — including CIPC pre-created directors — use director-ubo-update instead.

Request body (example):

{
  "firstName": "John",
  "lastName": "Doe",
  "addressLine1": "123 Example Street",
  "addressLine2": "Example Suburb",
  "addressLine3": "Example City",
  "addressZipCode": "8001",
  "addressCountry": 189,
  "clientSACitizen": true,
  "idNumber": "8001015009087",
  "shareholderPercentage": "25",
  "isDirector": true,
  "isShareholder": true,
  "externalId": "your-ubo-ref-optional"
}

Field	Notes
`clientSACitizen`	`true` requires `idNumber`; `false` requires `passportNumber` and `passportCountry`
`shareholderPercentage`	String percentage (e.g. `"25"`)
`isDirector` / `isShareholder`	Role flags

Response includes uboUUID and screening results for review.

Update a director or UBO

Endpoint: PATCH /api/v1/entity/:id/director-ubo-update

Path parameter: :id = UBO UUID (not entity UUID)

Use on both showOrganigram paths to complete or correct personal data for an existing UBO — including CIPC pre-created directors and individuals returned from organigram verify.

Same request body as create. Screening is re-run only when results are not already stored.

PEP and sanctions review

Endpoint: PATCH /api/v1/entity/:id/ubo-pep-confirm

Path parameter: :id = UBO UUID

Record your review of the UBO's screening results before uploading documents.

{
  "adverseSearchKYC": false,
  "pepConfirmReviewed": true
}

Response:

{
  "riskStatus": "Low Risk",
  "riskReason": "The UBO calculated risk score (2) is within the low risk range. (1 to 14)"
}

Use riskStatus to determine which document groups are required — see Documents.

UBO documents

Determine required documents first

After PEP confirm, use the returned riskStatus with GET /api/v1/settings/individual-docs and individual-doc-types to build the list of document groups and types this UBO must upload. See Documents.

Upload (repeat for each required document)

Endpoint: POST /api/v1/entity/:id/ubo-doc-upload

Path parameter: :id = UBO UUID

Each request uploads one file for one document group + type pair. Call this endpoint multiple times until every required document is on file.

curl -X POST "https://sandboxapi.efica.co.za/api/v1/entity/{uboUUID}/ubo-doc-upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/id.pdf" \
  -F 'documents={"individualDocsID": 1, "IndividualDocTypesID": 1}'

Store each returned uboDocsID if you need to view or delete a file before confirming.

View and delete (optional)

Action	Endpoint	`:id` meaning
Get base64	`GET /api/v1/entity/:id/ubo-doc`	uboDocsID (integer)
Delete	`DELETE /api/v1/entity/:id/ubo-doc-delete`	uboDocsID (integer)

Confirm (once per UBO, after all uploads)

Endpoint: PATCH /api/v1/entity/:id/ubo-doc-confirm

Path parameter: :id = UBO UUID

Call this only after every required document for that UBO has been uploaded. Do not confirm after a single upload if more documents are still required.

{ "docsUploadedReviewed": true }

When docsUploadedReviewed is true, eFICA records that documents for this UBO have been reviewed and completes the UBO document step.

Example flow for one UBO

PEP confirm → riskStatus: "Low Risk"
Required docs: Identity (type 1), Proof of address (type 7) — from individual-docs
ubo-doc-upload — Identity
ubo-doc-upload — Proof of address
ubo-doc-confirm — only now

CIPC pre-created directors

When POST /api/v1/entity returns createdUbos (showOrganigram: false SA entities), those persons already exist in eFICA:

Present pre-filled details for confirmation.
Update via director-ubo-update if anything changed.
PEP confirm → upload all required documents → ubo-doc-confirm.

Use ubo-create only to add additional people not already in createdUbos.

Organigram UBOs

When showOrganigram is true:

Build the organigram (individuals, entities, trusts).
Call PATCH verify-organigram when the structure is complete — this creates all UBO and trust-member records.
For each person: director-ubo-update → PEP confirm → upload all required documents → ubo-doc-confirm.

Do not call ubo-create. Individual nodes with uboID: null on verify create new UBO records; the response returns each UBO UUID in uboID on the node and in the root ubos[] summary.

After verify, you cannot add more UBOs. Complete the full per-person loop for everyone before shareholding-confirm.

Profile image (Optional)

Endpoint: GET /api/v1/entity/ubo/:id/profile-image

Path parameter: :id = UBO UUID

Returns identity verification profile photo as base64 when available.

List directors and members

Endpoint	Purpose
`GET /api/v1/entity/:id/directors-and-members`	List all UBOs for an entity (`:id` = entity UUID)
`GET /api/v1/entity/directors-and-members/:uboID`	Get single UBO details
`DELETE /api/v1/entity/directors-and-members/:uboID`	Remove a UBO (`showOrganigram: false` only, before shareholding confirm)

Business analyst summary

For every person linked to the entity (repeat — there may be many):

Step	What to do
1. Update	Complete personal data (`director-ubo-update`). Add new people with `ubo-create` only when there is no organigram.
2. PEP confirm	Review sanctions and PEP results; record the decision.
3. Upload	Collect and upload every required document (by UBO risk band).
4. Confirm	Mark documents reviewed only when the full set is uploaded.

When showOrganigram is true, verify the organigram first — UBOs are created there, not via ubo-create. When all persons are done, call shareholding confirm on the entity. Entity-level documents come after that.

No UBO or trust individual can be skipped if they appear in the ownership structure or director list.

Documents — how UBO document requirements are determined
Organigram — trust members and related parties
Identifiers — UBO UUID vs document ID reference

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

UBO sources​

Per-UBO workflow​

Create a director or UBO​

Update a director or UBO​

PEP and sanctions review​

UBO documents​

Determine required documents first​

Upload (repeat for each required document)​

View and delete (optional)​

Confirm (once per UBO, after all uploads)​

CIPC pre-created directors​

Organigram UBOs​

Profile image (Optional)​

List directors and members​

Business analyst summary​

Related​

Document history​

Support​

UBO sources

Per-UBO workflow

Create a director or UBO

Update a director or UBO

PEP and sanctions review

UBO documents

Determine required documents first

Upload (repeat for each required document)

View and delete (optional)

Confirm (once per UBO, after all uploads)

CIPC pre-created directors

Organigram UBOs

Profile image (Optional)

List directors and members

Business analyst summary

Related

Document history

Support