Entities

Who this guide is for

This guide is written for business analysts (what happens, when, and why) and mid-level developers (endpoints, payloads, and implementation order) integrating entity (company) FICA onboarding through the Public API.

Use the sections below as a hub. Detailed guides are split into sub-pages so each topic stays focused.

Overview
Authentication
Prerequisites
Key concepts
End-to-end workflow
Choosing your integration path
Detailed guides
Linking to your external system
Error handling
Best practices

Overview

The eFICA Entity API allows you to create and manage FICA (Financial Intelligence Centre Act) compliance records for corporate clients. The workflow covers entity registration, Know Your Business (KYB) details, ownership structure, sanctions screening review, document collection for the entity and its ultimate beneficial owners (UBOs), and final onboarding decisions.

Key features

Complete FICA workflow: End-to-end entity client onboarding
CIPC integration: South African entities are enriched with Companies and Intellectual Property Commission (CIPC) commercial data on create
Ownership structure: Directors, shareholders, trusts, and related parties — with or without an organigram depending on entity type
AML screening: Automated sanctions and adverse media screening on entity create
Document management: Upload, view, and manage entity and UBO documents
PEP and sanctions review: Entity-level and per-UBO review steps
Onboarding decisions: Approve, decline, or refer entities for review
PDF FICA report: Download the completed entity application report

Base URLs

Sandbox: https://sandboxapi.efica.co.za
Production: https://api.efica.co.za

API version

All endpoints are under /api/v1/entity.

For lookup data (countries, entity types, document groups, and more), see the Settings Guide.

Authentication

All endpoints require OAuth2 Bearer token authentication:

Authorization: Bearer <your-oauth2-token>

For details on obtaining OAuth2 tokens, refer to the OAuth2 Integration Guide.

Important: If there is insufficient balance in your account, the entity record will not be created in Step 1.

Prerequisites

Before starting entity onboarding, call these settings endpoints and cache the results for your integration:

Purpose	Endpoint
Entity types (legal structure, organigram flag)	`GET /api/v1/settings/entity-types`
Entity document groups	`GET /api/v1/settings/entity-docs`
Entity document types	`GET /api/v1/settings/entity-doc-types`
UBO document groups	`GET /api/v1/settings/individual-docs`
UBO document types	`GET /api/v1/settings/individual-doc-types`
Trust related-party types (organigram)	`GET /api/v1/settings/trust-related-party-types`
Countries, industries, transaction settings	See Settings Guide

See Documents for how document requirements are determined from risk level.

Key concepts

Term	Meaning
Entity	The corporate FICA record (company, close corporation, etc.)
Entity UUID	Stable primary key returned as `id` on create — use in all entity-scoped API calls
UBO	Ultimate beneficial owner — director, shareholder, trust member, or related party linked to the entity
UBO UUID	Stable key for a UBO record — returned when UBOs are created; required for UBO-scoped endpoints
Client reference	Your optional external reference for the entity (CRM account number, loan reference, etc.)
Organigram	Ownership structure tree showing who owns the entity — individuals, trusts, and other entities with share percentages
Risk band	`Low Risk`, `Medium Risk`, or `High Risk` — determines which documents are required
CIPC	Companies and Intellectual Property Commission — South African company registry used to pre-fill entity and director data

For a full identifier reference (including path parameter pitfalls), see Identifiers.

End-to-end workflow

The diagram below shows the high-level entity onboarding flow. The ownership step branches based on entity type — see Choosing your integration path.

The per-person UBO loop repeats for every UBO and trust individual. Entity documents start only after all persons are complete and shareholding-confirm has been called — upload each required entity document in a loop, then entity-doc-confirm once.

Choosing your integration path

After calling GET /api/v1/settings/entity-types, check two flags on the selected entity type:

`showOrganigram`

Both paths end with the same per-person UBO steps and PATCH shareholding-confirm. Entity documents come after that.

Value	What differs before the UBO loop
`false`	View directors and members; add or edit users on a flat list (e.g. Close Corporation)
`true`	Build an organigram of individuals, entities, and trusts; then `PATCH verify-organigram` when the structure is complete

Per-person steps — repeat for each UBO and trust individual (steps 2–3 are the same on both paths; step 1 differs):

Update UBO — PATCH director-ubo-update on both paths. POST ubo-create only when showOrganigram is false (to add a person not already on the entity).
PEP confirm — PATCH ubo-pep-confirm
Documents — upload all required documents (ubo-doc-upload, one per file), then PATCH ubo-doc-confirm once when every required document is on file

When showOrganigram is true, UBOs come from verify-organigram — you cannot call ubo-create or add UBOs after the organigram is verified.

See Organigram and UBOs for details.

`foreignEntityType`

Value	Behaviour
`false`	CIPC lookup on create; directors may be pre-created from CIPC principal data
`true`	No CIPC lookup; you must add all directors and UBOs manually

Workflow completion flags

Poll GET /api/v1/entity/:id to track progress. Key boolean/string flags include:

ownershipStructureReviewed — ownership step complete
organigramReviewed — organigram finalised (organigram entity types)
docsUploadedReviewed — entity documents confirmed
sanctionSearchCompleted — entity sanctions review recorded
directorsConfirmed / directorsReviewed — director list steps
ficaStatus, riskDescription — overall status and risk

Detailed guides

Guide	Contents
Workflow	Step-by-step implementation with mandatory vs optional steps
Organigram	Ownership structure tree, node types, bulk vs incremental integration
Documents	How required documents are determined; entity and UBO upload flows
UBOs	Creating, updating, and completing each UBO
Identifiers	Entity UUID, UBO UUID, document IDs, and path parameter reference

Linking to your external system

When you drive onboarding through the Public Entity API, your integration owns the workflow. Store identifiers from API responses and use them on subsequent calls:

Entity UUID — from id on POST /api/v1/entity; required for all entity-scoped endpoints.
UBO UUID — from create/update/organigram verify responses; required for per-person endpoints.
Client reference — optional clientReference on create for your CRM or loan system label.
External system ID — optional externalSystemId on create, or PATCH /api/v1/entity/update-external-system-id later.

Webhooks are a separate integration

The Public Entity API does not emit webhooks. Webhooks notify your system when users make changes in the eFICA UI (if you subscribe). That is documented separately in Entity Webhooks — use it only for UI-driven sync, not for Public API onboarding flows.

Error handling

Common HTTP status codes

Status	Description	Common causes
200	Success	Request completed
201	Created	Resource created (entity, document, UBO)
400	Bad Request	Validation failed, invalid organigram, file too large
401	Unauthorized	Missing or invalid OAuth2 token
403	Forbidden	Onboarding decision locked (already approved or declined)
404	Not Found	Entity, UBO, or document not found
500	Internal Server Error	Server error

Error response format

{
  "statusCode": 400,
  "message": "Bad Request",
  "error": "Validation failed"
}

Common scenarios

Insufficient balance (create)
The entity record is not created. Check account balance before onboarding.

Wrong path parameter type
Several endpoints use :id for different identifiers (entity UUID, UBO UUID, or numeric document ID). See Identifiers.

Organigram already finalised
Incremental organigram node changes are rejected after the structure is confirmed.

Onboarding decision locked
Returns 403 when the entity is already approved or declined.

Best practices

Workflow

Follow the step sequence — later steps depend on earlier completion flags.
Store the entity UUID from create for all subsequent calls.
Store each UBO UUID when UBOs are created for per-person steps.
Branch on showOrganigram and foreignEntityType before building your UI.

Documents

Cache settings document groups at onboarding start.
Re-evaluate required documents when entity or UBO risk changes.
Upload one document group + type per request on the canonical endpoints.

Security

Never expose OAuth2 tokens in client-side code.
Always use HTTPS.
Implement token refresh for long-running integrations.

Testing

Test in sandbox before production.
Test both organigram and non-organigram entity types.
Test foreign entity types separately (no CIPC pre-fill).
Poll GET /api/v1/entity/:id for workflow completion flags — do not rely on webhooks for Public API flows.

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

Who this guide is for​

Table of Contents​

Overview​

Key features​

Base URLs​

API version​

Authentication​

Prerequisites​

Key concepts​

End-to-end workflow​

Choosing your integration path​

showOrganigram​

foreignEntityType​

Workflow completion flags​

Detailed guides​

Linking to your external system​

Error handling​

Common HTTP status codes​

Error response format​

Common scenarios​

Best practices​

Workflow​

Documents​

Security​

Testing​

Document history​

Support​