Entity and UBO documents

This page explains how your integration determines which documents to collect and how to upload them. It covers both entity-level documents and UBO-level documents.

Workflow order

• UBO documents are collected during the per-person loop: upload each required file via ubo-doc-upload, then call ubo-doc-confirm once when the full set is on file — before shareholding-confirm.
• Entity documents are collected only after every UBO/trust individual is complete and PATCH shareholding-confirm has succeeded. Upload each required file via entity-doc, then call entity-doc-confirm once when the full set is on file.

---

Document hierarchy

eFICA uses a two-level document model:

1. Document groups — parent categories (e.g. "Company Address", "Identity")
2. Document types — specific variants within a group (e.g. "Certificate of Incorporation")

You need both IDs when uploading: a group ID and a type ID.

Scope	Groups endpoint	Types endpoint
Entity	GET /api/v1/settings/entity-docs	GET /api/v1/settings/entity-doc-types
UBO	GET /api/v1/settings/individual-docs	GET /api/v1/settings/individual-doc-types

important

UBO documents use the individual settings endpoints, not entity-docs — even though the person is linked to an entity.

---

How required documents are determined

Document requirements depend on the risk band of the entity or UBO. eFICA uses three bands:

• Low Risk
• Medium Risk
• High Risk

When is risk known?

Record	Risk source	Typical endpoint
Entity	riskStatus after shareholding confirm	PATCH shareholding-confirm (both showOrganigram paths)
UBO	riskStatus after PEP review	ubo-pep-confirm (during per-person loop, before shareholding confirm)

Entity documents — filtering algorithm

1. Call GET /api/v1/settings/entity-docs and cache the result (partner-specific if configured).
2. Determine the entity risk band (e.g. "Low Risk" from shareholding-confirm response).
3. For each active document group, check the matching required flag:

Risk band	Required flag	Description field
Low Risk	requiredLowRisk	descriptionLowRisk
Medium Risk	requiredMediumRisk	descriptionMediumRisk
High Risk	requiredHighRisk	descriptionHighRisk

4. Display groups where the required flag is true.
5. Use description* text as helper copy for business users (what to collect and how).
6. For each required group, call GET /api/v1/settings/entity-doc-types and filter types where docID matches the group's id.

Example — entity-docs response:

{
  "id": 2,
  "name": "Company Address",
  "descriptionHighRisk": "Copy of proof of address original sighted",
  "descriptionLowRisk": "Copy of proof of address",
  "descriptionMediumRisk": "Copy of proof of address",
  "requiredLowRisk": false,
  "requiredMediumRisk": false,
  "requiredHighRisk": true,
  "active": true
}

For a High Risk entity, "Company Address" is required and you show the high-risk description to the user.

UBO documents — filtering algorithm

1. Call GET /api/v1/settings/individual-docs and cache the result.
2. Determine the UBO risk band from ubo-pep-confirm (riskStatus).
3. For each active document group, check the matching required flag:

Risk band	Required flag	Description field
Low Risk	lowRiskRequired	lowRiskDescription
Medium Risk	mediumRiskRequired	mediumRiskDescription
High Risk	highRiskRequired	highRiskDescription

4. Display groups where the required flag is true.
5. Fetch types from GET /api/v1/settings/individual-doc-types; match on docID.

Field naming difference

Entity-docs uses requiredLowRisk / requiredMediumRisk / requiredHighRisk. Individual-docs uses lowRiskRequired / mediumRiskRequired / highRiskRequired.

Pseudocode (developers)

function requiredEntityDocGroups(entityDocs, riskBand) {
  const map = {
    'Low Risk':    { req: 'requiredLowRisk',    desc: 'descriptionLowRisk' },
    'Medium Risk': { req: 'requiredMediumRisk', desc: 'descriptionMediumRisk' },
    'High Risk':   { req: 'requiredHighRisk',   desc: 'descriptionHighRisk' },
  };
  const { req, desc } = map[riskBand];
  return entityDocs
    .filter(g => g.active && g[req])
    .map(g => ({ id: g.id, name: g.name, description: g[desc] }));
}

function requiredUboDocGroups(individualDocs, riskBand) {
  const map = {
    'Low Risk':    { req: 'lowRiskRequired',    desc: 'lowRiskDescription' },
    'Medium Risk': { req: 'mediumRiskRequired', desc: 'mediumRiskDescription' },
    'High Risk':   { req: 'highRiskRequired',   desc: 'highRiskDescription' },
  };
  const { req, desc } = map[riskBand];
  return individualDocs
    .filter(g => g.active && g[req])
    .map(g => ({ id: g.id, name: g.name, description: g[desc] }));
}

---

Uploading entity documents

Workflow

1. Complete shareholding-confirm and read riskStatus from the response.
2. Filter entity-docs / entity-doc-types to get the full list of required entity documents for that risk band.
3. Call entity-doc once per required document (one file per request).
4. Call entity-doc-confirm only after every required entity document has been uploaded.

important

Do not call entity-doc-confirm after the first upload if more required documents remain. Confirm is a single completion step for the whole document set.

Upload endpoint

POST /api/v1/entity/:id/entity-doc

• Path :id = entity UUID
• One document group + type per request — repeat for each required document
• Multipart form fields:
  • file (binary, required)
  • documents (JSON string, required): {"entityDocsID": 2, "entityDocTypesID": 1}
  • additionalFicaDoc (optional)

Response:

{ "entityDocID": 123 }

Store each entityDocID for view/delete operations.

Example flow

1. shareholding-confirm → riskStatus: "High Risk"
2. Required docs: Company Address (type 2), Registration (type 1) — from entity-docs
3. entity-doc — Company Address
4. entity-doc — Registration
5. entity-doc-confirm — only now

View and delete

Action	Endpoint	Path :id
Get base64	GET /api/v1/entity/:id/entity-doc	entityDocID (integer)
Delete	DELETE /api/v1/entity/:id/entity-doc	entityDocID (integer)

Confirm entity documents

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

Path :id = entity UUID. Call once per entity when all required uploads are complete.

{ "docsUploadedReviewed": true }

---

Uploading UBO documents

See UBOs for the full per-UBO workflow.

Workflow per UBO

1. Complete PEP confirm and read riskStatus from the response.
2. Filter individual-docs / individual-doc-types to get the full list of required documents for that risk band.
3. Call ubo-doc-upload once per required document (one file per request).
4. Call ubo-doc-confirm only after every required document has been uploaded.

important

Do not call ubo-doc-confirm after the first upload if more required documents remain. Confirm is a single completion step for the whole document set.

Upload endpoint

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

• Path :id = UBO UUID
• One document group + type per request — repeat for each required document
• Multipart form fields:
  • file (binary, required)
  • documents (JSON string, required): {"individualDocsID": 1, "IndividualDocTypesID": 1}
  • additionalFicaDoc (optional)

Response:

{ "uboDocsID": 456 }

View and delete

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

Confirm UBO documents

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

Path :id = UBO UUID. Call once per UBO when all required uploads are complete.

{ "docsUploadedReviewed": true }

---

File requirements

Constraint	Value
Supported formats	PDF, PNG, JPEG, JPG
Maximum file size	Default 40MB (configurable server-side)
Uploads per request	One file; one group + type pair

---

Business analyst checklist

For each onboarding case:

UBO documents (during per-person loop, before shareholding confirm)

• Each UBO and trust individual: data updated → PEP confirmed → all required documents uploaded → ubo-doc-confirm

Entity documents (after all UBOs complete and shareholding confirmed)

• Entity risk band confirmed (from shareholding-confirm response)
• Required groups identified from entity-docs
• Correct descriptions shown to client per risk band
• All required entity documents uploaded (entity-doc per file)
• Entity documents reviewed and confirmed (entity-doc-confirm — once, after full set)

---

Related

• Workflow — when document steps occur in the sequence
• UBOs — per-person PEP and document workflow
• Identifiers — document ID reference
• Settings — full settings endpoint reference

Endpoint Summary

Endpoint	Method	Authentication	Description
/api/v1/services/individual/{individualUUID}/bank-account-verification	POST	Bearer (OAuth2)	Verify an individual bank account

---

---

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