Entity integration identifiers
This page lists the identifiers your integration must store and explains a common source of integration errors: the :id path parameter means different things on different routes.
Primary identifiers
| Identifier | Where you get it | Use for |
|---|---|---|
| Entity UUID | id in POST /api/v1/entity response | All entity-scoped routes (:id = entity UUID) |
| UBO UUID | uboUUID in create UBO responses; uboID in organigram verify response | UBO-scoped routes (PEP confirm, doc upload, doc confirm) |
| Entity trust UUID | Trust node id after organigram verify | Trust organigram nodes |
| Client reference | You supply on create (clientReference) | Your CRM or external label for the entity |
| External system ID | You supply (externalSystemId) or set via update-external-system-id | Your system's primary key for the entity |
Always store the entity UUID when the record is created. Use it on every subsequent Public API call for that entity.
Path parameter :id reference
The same path parameter name :id refers to different identifier types depending on the endpoint.
| Endpoint | :id meaning |
|---|---|
GET /api/v1/entity/:id | Entity UUID |
PATCH /api/v1/entity/:id/kyb | Entity UUID |
PATCH /api/v1/entity/:id/sanctions-review | Entity UUID |
POST /api/v1/entity/:id/ubo-create | Entity UUID — only when showOrganigram is false |
PATCH /api/v1/entity/:id/director-ubo-update | UBO UUID |
PATCH /api/v1/entity/:id/ubo-pep-confirm | UBO UUID |
POST /api/v1/entity/:id/ubo-doc-upload | UBO UUID |
PATCH /api/v1/entity/:id/ubo-doc-confirm | UBO UUID |
PATCH /api/v1/entity/:id/shareholding-confirm | Entity UUID |
PATCH /api/v1/entity/:id/verify-organigram | Entity UUID |
POST /api/v1/entity/:id/entity-doc | Entity UUID |
PATCH /api/v1/entity/:id/entity-doc-confirm | Entity UUID |
PATCH /api/v1/entity/:id/onboarding-decision | Entity UUID |
GET /api/v1/entity/:id/ubo-doc | uboDocsID (integer) |
DELETE /api/v1/entity/:id/ubo-doc-delete | uboDocsID (integer) |
GET /api/v1/entity/:id/entity-doc | entityDocID (integer) |
DELETE /api/v1/entity/:id/entity-doc | entityDocID (integer) |
GET /api/v1/entity/ubo/:id/profile-image | UBO UUID |
Document record IDs
When you upload a document, the response returns a numeric record ID. Store these for view and delete operations.
| Upload endpoint | Response field | Used on |
|---|---|---|
POST .../entity-doc | entityDocID | GET / DELETE .../entity-doc |
POST .../ubo-doc-upload | uboDocsID | GET / DELETE .../ubo-doc |
Organigram node identifiers
| Phase | Field name | Notes |
|---|---|---|
| Request (your system) | guid | Stable UUID you assign per node in the tree |
| Response (after verify) | id | eFICA-assigned UUID; same logical node as your guid |
| Trust nodes | trustID / ficaEntityTrustGUID | Entity trust UUID for trust shareholder nodes |
| Individual nodes | uboID | UBO UUID after UBO record is created or matched |
When calling PATCH verify-organigram again to update an existing structure, pass the UBO UUID in uboID on Individual nodes that already exist.
Settings lookup IDs
These are numeric IDs from settings endpoints, not UUIDs:
| ID | Source endpoint | Used when uploading |
|---|---|---|
entityDocsID | GET /api/v1/settings/entity-docs → id | Entity document upload |
entityDocTypesID | GET /api/v1/settings/entity-doc-types → id | Entity document upload |
individualDocsID | GET /api/v1/settings/individual-docs → id | UBO document upload |
IndividualDocTypesID | GET /api/v1/settings/individual-doc-types → id | UBO document upload |
entityType | GET /api/v1/settings/entity-types → id | Entity create |
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