Entity Webhooks — Integration Guide

This document describes all webhook event types related to corporate entities in eFICA: the main entity record, entity documents, entity trusts (organigram trust nodes), and UBOs (ultimate beneficial owners). It is written for business analysts (what happens, when, and why) and mid-level developers (payloads, routing, and implementation notes).

1. Overview (business)

What these webhooks do

External partner systems can subscribe to entity-related events to stay aligned with eFICA when:

A new entity (company) FICA record is opened
An existing entity is updated through the FICA workflow
Documents are uploaded or removed on an entity
A trust node is added or changed on the entity ownership organigram
A UBO (director, shareholder, or related party) is created or updated, or has documents added or removed

How delivery works

An action in eFICA (UI or public API) verifies if your subscription has the eventType and is enabled.
If enabled, a delivery is queued to your URL.
A background job POSTs the JSON payload to your endpoint (typically within seconds).
Delivery is at-least-once: retries may cause duplicates; use eventId to deduplicate.

Where to configure subscriptions

eFICA UI: eFICA Settings → Integrations → Webhooks (create/edit subscription, select event types).
This can only be performed by a user with an admin role.

Event catalogue (entity domain)

Event type	Business meaning	Typical trigger
`entity.created`	New entity FICA record created	Create entity in eFICA (UI or public API); automated director import during entity setup
`entity.updated`	Entity record or workflow step changed	FICA step saves, risk/onboarding updates, organigram-related entity touch, API updates
`entity.document.created`	Entity document uploaded	Document upload (UI or public API)
`entity.document.deleted`	Entity document soft-deleted	Document delete (UI or public API)
`entityTrust.created`	Trust shareholder node added to organigram	Add organigram node with type Trust
`entityTrust.updated`	Trust node details changed	Update organigram trust node
`ubo.created`	New UBO/director/related party record	New UBO saved on an entity
`ubo.updated`	UBO record updated	Existing UBO saved on an entity
`ubo.document.created`	Document uploaded for a UBO	UBO document upload
`ubo.document.deleted`	UBO document soft-deleted	UBO document delete

2. Shared concepts (business + technical)

Primary key: eFICA Entity UUID

Always use sourceId (entity events) or entityId (child events) as the stable identifier for the corporate entity in your system. This value is the eFICA entity UUID assigned when the entity record is created.

Store this UUID when you first process entity.created (from sourceId) and use it to match all subsequent entity.updated, document, trust, and UBO events for that entity.

Other identifiers

Field	Meaning	Who sets it
eFICA Entity UUID (`sourceId` / `entityId`)	Required for routing — stable primary key for the entity in eFICA	eFICA on entity create
Client reference (`clientRef` in `data`, `externalID` on envelope when present)	Optional partner reference for the entity (CRM / loan account / custom label)	Partner user or integration; may be empty
UBO UUID (`uboId` in payload, `sourceId` on UBO events)	Stable key for a UBO record	eFICA on UBO create
Entity trust UUID (`entityTrustId` in payload, `sourceId` on trust events)	Stable key for an organigram trust node	eFICA on trust node create
eventId	Unique ID for this webhook delivery occurrence	eFICA (UUID) — use for idempotency

Routing rules (important for integrations)

Event	Primary routing key	`externalID` on envelope	When event is not emitted
`entity.created`	`sourceId` (entity UUID)	Always `null`	Missing partner or entity UUID
`entity.updated`	`sourceId` (entity UUID)	`clientRef` when set; otherwise `null` or empty	Missing partner or entity UUID only
`entity.document.*`	`entityId` (entity UUID)	Optional `clientRef`	Missing partner or entity UUID
`entityTrust.*`	`entityId` + `entityTrustId`	Optional `clientRef`	Missing partner, entity UUID, or trust UUID
`ubo.*`	`entityId` + `uboId`	Optional `clientRef`	Missing partner, entity UUID, or UBO UUID

Business implication

You do not need a client reference or external system ID before receiving entity.updated. Link your external record using sourceId / entityId (eFICA entity UUID).
On entity.created, externalID is null by design — create your external record keyed by sourceId, then optionally store data.clientRef when the user adds one later.
If you maintain your own external reference, data.clientRef and externalID are convenience fields only; they may be empty on many events.

Admin user fields

Fields such as adminAdded, adminUpdated, uploadAdminId are eFICA user GUIDs (not numeric user IDs).

Screening and validation JSON

Field	Description
`amlScreeningResults`	AML / sanctions screening summary (JSON). Treat as an opaque object unless your integration agreement defines specific keys.
`clientValidationResults`	Entity commercial / registry validation summary (JSON). Treat as an opaque object unless your integration agreement defines specific keys.

Internal provider details are stripped before send; do not depend on undocumented nested fields.

Payload envelope (all events)

Every delivery body is JSON with:

{
  "schemaVersion": 1,
  "eventId": "<uuid>",
  "eventType": "<event.type>",
  "occurredAt": "<ISO-8601 UTC>",
  "...": "event-specific top-level fields",
  "data": { }
}

HTTP headers: X-Efica-Event-Id, X-Efica-Event-Type, X-Efica-Signature, Content-Type: application/json.

3. Entity record events

3.1 `entity.created`

When it fires

A new entity FICA record is created in eFICA (UI or public API).
Automated creation of director/UBO records during initial entity setup also triggers this event for the entity when the entity itself is newly created.

When it does not fire

Updates to an existing entity (use entity.updated).
Trust-only or UBO-only changes without a new entity (use entityTrust.* or ubo.*).

Routing

sourceId = eFICA entity UUID — store this in your system.
externalID = null.
data.clientRef = optional client reference if already captured.

Example payload

{
  "schemaVersion": 1,
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventType": "entity.created",
  "occurredAt": "2026-05-21T10:00:00.000Z",
  "source": "Entity",
  "sourceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalID": null,
  "data": {
    "ficaStatus": "In Progress",
    "registeredName": "Example (Pty) Ltd",
    "registrationNumber": "2020/123456/07",
    "riskDescription": "Undetermined",
    "clientRef": null,
    "entityType": 2,
    "transactionFrequency": 1,
    "adminAdded": "9b8c7d6e-5f4a-3210-9876-543210fedcba",
    "dateAdded": "2026-05-21T10:00:00.000Z"
  }
}

data fields

Field	Type	Description
`ficaStatus`	string	Entity FICA status (e.g. In Progress)
`registeredName`	string \| null	Registered / legal name
`registrationNumber`	string \| null	Registration number
`riskDescription`	string	Risk label (e.g. Undetermined, Low Risk)
`clientRef`	string \| null	Optional client reference on entity
`entityType`	number \| null	Entity type identifier
`transactionFrequency`	number \| null	Transaction frequency lookup identifier
`adminAdded`	string \| null	User UUID who created the record
`dateAdded`	string \| null	ISO timestamp

3.2 `entity.updated`

When it fires

Whenever the entity record is saved after material workflow changes, including (non-exhaustive):

Entity FICA step saves, onboarding decision, risk recalculation
Organigram-related updates that touch the parent entity
Public API entity updates

When it does not fire

Missing partner or entity UUID (enqueue skipped).
Child-only changes that do not update the parent entity record (documents, UBO-only, trust-only — use the matching child event types).

Routing

sourceId = eFICA entity UUID — use this to find the record in your system.
externalID = optional copy of data.clientRef when a client reference exists; may be null or omitted when not set.
Do not require externalID to be present to process the event.

Example payload (abbreviated)

{
  "schemaVersion": 1,
  "eventId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "eventType": "entity.updated",
  "occurredAt": "2026-05-21T11:30:00.000Z",
  "sourceEntity": "FICA_ENTITY",
  "sourceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalID": null,
  "entityType": 2,
  "data": {
    "ficaStatus": "In Progress",
    "entityRisk": "Medium Risk",
    "riskReason": "Calculated risk score within medium range",
    "clientRef": null,
    "registeredName": "Example (Pty) Ltd",
    "registrationNumber": "2020/123456/07",
    "amlScreeningResults": {},
    "clientValidationResults": {},
    "adminUpdated": "9b8c7d6e-5f4a-3210-9876-543210fedcba",
    "dateUpdated": "2026-05-21T11:30:00.000Z",
    "directorsConfirmed": true,
    "organigramReviewed": false,
    "docsUploadedReviewed": true,
    "onboardingDecision": "Approved",
    "onboardingDecisionReason": null,
    "nextFicaReviewDate": "2027-05-21T00:00:00.000Z"
  }
}

data fields (grouped for analysts)

Group	Fields	Purpose
Core	`ficaStatus`, `entityRisk`, `riskReason`, `clientRef`, `registeredName`, `registrationNumber`, `sameEntityName`, `cipcCommercialName`	Status and identification
Screening	`amlScreeningResults`, `clientValidationResults`, `adverseSearchResults`	AML screening and entity validation summaries
Address & contact	`addressLine1`–`3`, `zipCode`, `country`, `entityTel`, `physicalAddress`, `postalAddress`	Location and contact
Workflow flags	`directorsConfirmed`, `directorsReviewed`, `sanctionSearchCompleted`, `shareholdersAdminConfirmed`, `organigramReviewed`, `docsUploadedReviewed`, `additionalVerification`	Step completion indicators (boolean where applicable)
Onboarding	`onboardingAdminID`, `onboardingAdminDate`, `onboardingDecision`, `onboardingDecisionReason`, `nextFicaReviewDate`, `referralAdminID`, `referredToAdminID`, `referralDate`	Decision and referral
Other	`countriesTradedWith`, `customFormAnswers`, industry/source-of-wealth/funding fields, `transactionFrequency`, `transactionClientConsistent`	Compliance questionnaire data

Developer note: Some numeric admin identifiers may appear in data alongside user UUID fields. Prefer UUID fields (adminUpdated, etc.) for cross-system references.

4. Entity document events

4.1 `entity.document.created`

When it fires: After a successful document upload and document record creation (UI or public API).

4.2 `entity.document.deleted`

When it fires: After a document is soft-deleted (active set to false).

Routing (both)

entityId = parent eFICA entity UUID.
externalID = optional clientRef; may be empty.
entityDocID = document identifier in eFICA.

Example (entity.document.created)

{
  "schemaVersion": 1,
  "eventId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "eventType": "entity.document.created",
  "occurredAt": "2026-05-21T12:00:00.000Z",
  "sourceEntity": "FICA_ENTITY_DOC",
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalID": null,
  "entityDocID": 1042,
  "data": {
    "docGroupID": 3,
    "docTypeID": 12,
    "docName": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.pdf",
    "active": true,
    "uploadDate": "2026-05-21T12:00:00.000Z",
    "uploadAdminId": "9b8c7d6e-5f4a-3210-9876-543210fedcba",
    "deleteAdminDate": null,
    "deleteAdminId": null
  }
}

Field	Description
`docGroupID`	Document group identifier
`docTypeID`	Document type identifier
`docName`	Internal storage key for the file (not a direct public download URL)
`active`	Whether the document is active
`uploadAdminId` / `deleteAdminId`	User GUIDs

Business note: Downloading the file typically requires a separate eFICA document API, not the webhook alone.

5. Entity trust events (organigram)

Entity trusts are trust shareholders on the entity ownership organigram, not standalone trust FICA products (trust.created / trust.updated are separate product events, not covered here).

5.1 `entityTrust.created`

When it fires: Adding an organigram node with shareholder type Trust.

5.2 `entityTrust.updated`

When it fires: Updating an existing trust node on the organigram.

Routing (both)

entityId = parent eFICA entity UUID.
entityTrustId = entity trust UUID.
sourceId on the stored event = entity trust UUID.
externalID = optional parent clientRef.

Example (entityTrust.created)

{
  "schemaVersion": 1,
  "eventId": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "eventType": "entityTrust.created",
  "occurredAt": "2026-05-21T13:00:00.000Z",
  "sourceEntity": "FICA_ENTITY_TRUST",
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "entityTrustId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "externalID": null,
  "data": {
    "trustName": "Family Trust ABC",
    "trustStatus": "In Progress",
    "riskStatus": "Undetermined",
    "sharePercentage": 25.0,
    "uboPercentage": 25.0,
    "adminAdded": "9b8c7d6e-5f4a-3210-9876-543210fedcba",
    "dateAdded": "2026-05-21T13:00:00.000Z"
  }
}

entityTrust.updated additional fields: adminUpdated, adminUpdateName, dateUpdated.

6. UBO events

A UBO is a director, shareholder, or trust-related party linked to an entity, created manually or through automated import during entity setup.

6.1 `ubo.created`

When it fires: A new UBO record is saved on an entity.

6.2 `ubo.updated`

When it fires: An existing UBO record is saved.

Routing (both)

entityId = parent eFICA entity UUID.
uboId = UBO UUID.
sourceId on the stored event = UBO UUID.
externalID = optional parent clientRef.

Example (ubo.created, abbreviated)

{
  "schemaVersion": 1,
  "eventId": "e5f6a7b8-c9d0-1234-ef01-345678901234",
  "eventType": "ubo.created",
  "occurredAt": "2026-05-21T14:00:00.000Z",
  "sourceEntity": "FICA_UBO",
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "uboId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalID": null,
  "data": {
    "firstName": "Jane",
    "lastName": "Doe",
    "fullName": null,
    "ficaStatus": "In Progress",
    "riskStatus": "Undetermined",
    "uboVerifiedStatus": "In Progress",
    "uboVerifiedRiskStatus": "Undetermined",
    "isDirector": true,
    "isShareholder": true,
    "shareholderPercentage": 50.0,
    "entityTrustID": null,
    "amlScreeningResults": null,
    "adminAdded": "9b8c7d6e-5f4a-3210-9876-543210fedcba",
    "dateAdded": "2026-05-21T14:00:00.000Z"
  }
}

Notable data fields (UBO created/updated)

Field	Description
`saCitizen`, `citizenshipCountry`, `residenceCountry`	Citizenship / residence
`identificationNumber`, `passportNumber`, `identificationType`	Identity documents
`addressLine1`–`3`, `zipCode`, `country`, `physicalAddress`, `postalAddress`	Address
`foreignOffical`, `foreignOfficalType`	PEP indicators
`cipcData`	Commercial registry verification payload (JSON object)
`consumerDetail`, `kycResult`	Identity / KYC result payloads (JSON) where present
`faceMatchResult`	Face-match verification summary when present
`entityTrustID`	Set when the UBO is linked to an entity trust related party
`ubo.updated` only	`clientRiskScore`, `riskReason`, `adminUpdated`, `dateUpdated`

6.3 `ubo.document.created` / `ubo.document.deleted`

When they fire

Created: After a UBO document is uploaded.
Deleted: After a UBO document is soft-deleted.

Routing

entityId = parent eFICA entity UUID.
uboId = UBO UUID.
uboDocID = document identifier in eFICA.

Example (ubo.document.created)

{
  "schemaVersion": 1,
  "eventId": "f6a7b8c9-d0e1-2345-f012-456789012345",
  "eventType": "ubo.document.created",
  "occurredAt": "2026-05-21T15:00:00.000Z",
  "sourceEntity": "FICA_UBO_DOC",
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "uboId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalID": null,
  "uboDocID": 88,
  "data": {
    "docGroupID": 1,
    "docTypeID": 4,
    "docName": "uuid-filename.pdf",
    "active": true,
    "uploadDate": "2026-05-21T15:00:00.000Z",
    "uploadAdminId": "9b8c7d6e-5f4a-3210-9876-543210fedcba",
    "deleteAdminDate": null,
    "deleteAdminId": null
  }
}

7. Subscribing to entity webhooks

Recommended starter set

{
  "name": "Entity FICA sync",
  "url": "https://your-system.com/api/efica/webhooks",
  "enabled": true,
  "eventTypes": [
    "entity.created",
    "entity.updated",
    "entity.document.created",
    "entity.document.deleted",
    "entityTrust.created",
    "entityTrust.updated",
    "ubo.created",
    "ubo.updated",
    "ubo.document.created",
    "ubo.document.deleted"
  ]
}

Public API example

POST /api/v1/webhooks/subscriptions
Authorization: Bearer <oauth2_access_token>
Content-Type: application/json

Use the same eventTypes array as above. Store the returned secret once; it is not shown again.

UI

eFica Settings → Integrations → Webhooks — sections Entity, Entity Trust, and UBO map to the event types above.

8. Implementation checklist (developers)

Verify signature on every request.
Dedupe on eventId (return 2xx quickly; process async if needed).
On entity.created, persist sourceId (eFICA entity UUID) as your foreign key to eFICA.
On all later events, resolve the parent entity by sourceId or entityId — not by externalID alone.
Treat externalID / clientRef as optional enrichment when your users populate client reference in eFICA.
Child events (entity.document.*, entityTrust.*, ubo.*): resolve parent via entityId; use uboId / entityTrustId for child records.
Inspect deliveries in eFICA: Settings → Integrations → Webhook Events.
Zero deliveries: Event is stored but no subscription matched — enable the event type on an enabled subscription for that partner.

9. Troubleshooting

Symptom	Likely cause
No webhook at all	Subscription disabled; event type not selected; enqueue skipped (missing entity UUID)
Event in UI but no HTTP call	No matching subscription (`eventTypes` must include the exact string, e.g. `"entity.updated"`)
Duplicate POSTs	Normal at-least-once behaviour; dedupe with `eventId`
Cannot match entity in your system	You keyed on `externalID` only — use `sourceId` / `entityId` (eFICA entity UUID) from `entity.created`
Wrong parent on UBO document	Join on `entityId` + `uboId`, not `uboDocID` alone

10. Entity - Mock Sample Response Data.

10.1 AML Screening Results - no search results found.

{
  "amlScreeningResults": {
      "metadata": {
        "message": "No match found for Sanctions and Adverse Media. "
      },
      "matchedNumber": 0,
      "matchedEntities": null,
      "webSearchResults": [
        {
          "title": "Example search result title - Example Site",
          "snippet": "Jan 01, 2025 ... Example snippet text returned from web search result.",
          "mime": null,
          "link": "https://www.example.com/example-search-result",
          "kind": "customsearch#result",
          "htmlTitle": "Example search result title - Example Site",
          "htmlSnippet": "Jan 01, 2025 <b>...</b> Example snippet text returned from web search result.",
          "htmlFormattedUrl": "https://www.example.com/example-search-result",
          "formattedUrl": "https://www.example.com/example-search-result",
          "fileFormat": null,
          "displayLink": "www.example.com"
        }
      ]
    }
}

10.2 CIPC Search Results.

{
  "clientValidationResults": {
      "Commercial": {
        "ReportInformation": {
          "ReportID": 3,
          "ReportName": "Commercial Enquiry Report"
        },
        "CommercialDirectorInformation": [
          {
            "DisplayText": "Commercial Director Information",
            "IDNo": 0000000000000,
            "FirstName": "FIRSTNAME SECONDNAME",
            "Initials": "F",
            "Surname": "SURNAME",
            "FullName": "FIRSTNAME SECONDNAME SURNAME",
            "BirthDate": "YYYY-MM-DD",
            "DirectorStatusCode": "Inactive",
            "AppointmentDate": "YYYY-MM-DD",
            "DirectorStatusDate": "",
            "MemberSize": 0,
            "PhysicalAddress": "123 EXAMPLE STREET, SUBURB, CITY, PROVINCE, 0000"
          }
        ],
        "CommercialAddressInformation": [
          {
            "DisplayText": "Commercial Address Information",
            "AddressType": "Physical",
            "Address1": "123 EXAMPLE STREET",
            "Address2": "SUBURB",
            "Address3": "CITY",
            "Address4": "PROVINCE",
            "PostalCode": 0000,
            "LastUpdatedDate": "YYYY-MM-DD"
          },
          {
            "DisplayText": "Commercial Address Information",
            "AddressType": "Postal",
            "Address1": "123 EXAMPLE STREET",
            "Address2": "SUBURB",
            "Address3": "CITY",
            "Address4": "PROVINCE",
            "PostalCode": 0000,
            "LastUpdatedDate": "YYYY-MM-DD"
          }
        ],
        "CommercialBusinessInformation": {
          "DisplayText": "Commercial Business Information",
          "CommercialName": "EXAMPLE COMPANY (PTY) LTD",
          "RegistrationNo": "K0000/000000/07",
          "BusinessStartDate": "YYYY-MM-DD",
          "FinancialYearEnd": "June",
          "RegistrationNoOld": "",
          "CommercialStatus": "AR Final Deregistration",
          "CommercialType": "Private Company",
          "SIC": "0 - Unknown Data",
          "TaxNo": 0000000000,
          "ReferenceNo": "B00000000-0000000",
          "ExternalReference": "eFICA",
          "TradeName": "",
          "PreviousBussName": "",
          "PhysicalAddress": "123 EXAMPLE STREET, SUBURB, CITY, PROVINCE, 0000",
          "PostalAddress": "123 EXAMPLE STREET, SUBURB, CITY, PROVINCE, 0000",
          "RegistrationDate": "YYYY-MM-DD",
          "BusinessDesc": "No Information Available",
          "TelephoneNo": "",
          "FaxNo": "",
          "BussEmail": "",
          "BussWebsite": "",
          "NoOfEnquiries": 0,
          "NameChangeDate": "",
          "AgeofBusiness": "X Years X Months",
          "AuthorisedCapitalAmt": 0,
          "IssuedNoOfShares": 0,
          "RegistrationNoConverted": "",
          "FinancialEffectiveDate": "",
          "AuthorisedNoOfShares": 1000,
          "IssuedCapitalAmt": 0,
          "CommercialStatusDate": "",
          "DirectorCount": 2,
          "VATNo": ""
        },
        "CommercialCompanyInformation": {
          "DisplayText": "Commercial Company Information",
          "CommercialName": "EXAMPLE COMPANY (PTY) LTD",
          "RegistrationNo": "K0000/000000/07",
          "RegistrationNoOld": "",
          "BusinessStartDate": "YYYY-MM-DD",
          "FinancialYearEnd": "June",
          "CommercialStatus": "AR Final Deregistration",
          "CommercialType": "Private Company",
          "SIC": "0 - Unknown Data",
          "TaxNo": 0000000000,
          "DirectorCount": 1,
          "ReferenceNo": "B00000000-0000000",
          "ExternalReference": "eFICA",
          "TradeName": "",
          "VATNo": "",
          "PreviousBussName": "",
          "NameChangeDate": "",
          "BussEmail": "",
          "BussWebsite": "",
          "LastUpdatedDate": "YYYY-MM-DD"
        },
        "CommercialPrincipalInformation": [
          {
            "DisplayText": "Commercial Principal Information",
            "DirectorID": 0000000,
            "IDNo": 0000000000000,
            "FirstName": "FIRSTNAME",
            "Initials": "F",
            "Surname": "SURNAME",
            "SecondName": "",
            "BirthDate": "YYYY-MM-DD",
            "DirectorStatusCode": "Active",
            "AppointmentDate": "YYYY-MM-DD",
            "Designation": "",
            "MemberSize": "R 0.00",
            "MemberControlPerc": 0,
            "DirectorIndicator": "YES",
            "PrincipalType": "Director",
            "CM29Date": "",
            "ISRSAResident": "Yes",
            "CountryCode": "ZA",
            "ISIDVerified": "Yes",
            "ISCIPROConfirmed": "Yes",
            "PhysicalAddress": "123 EXAMPLE STREET SUBURB CITY PROVINCE 0000",
            "PostalAddress": "123 EXAMPLE STREET SUBURB CITY PROVINCE 0000",
            "Name": "FIRSTNAME SURNAME",
            "HomeTelephoneNo": "0000000000",
            "WorkTelephoneNo": "0000000000",
            "CellularNo": "0000000000",
            "EmailAddress": "",
            "Age": "XX Years X Months",
            "YearsWithBusiness": "X Years X Months",
            "Fullname": "FIRSTNAME SECONDNAME SURNAME",
            "SurnamePrevious": "",
            "DirectorStatusDate": "YYYY-MM-DD",
            "MemberControlType": "",
            "Executor": "",
            "ExecutorAppointmentDate": "",
            "Estate": "",
            "ResignationDate": "",
            "ConsumerScore": 0,
            "PresageV3ExclusionRule": "",
            "ConsumerID": 00000000
          }
        ],
        "CommercialActivePrincipalInfoSummary": {
          "DisplayText": "Commercial Active Principal Info Summary",
          "NoOfPrincipals": 1,
          "NoOfInactivePrincipals": 0,
          "AverageAge": 0
        },
        "CommercialInActivePrincipalInfoSummary": {
          "DisplayText": "Commercial Inactive Principal Info Summary",
          "NoOfPrincipals": 0,
          "NoOfInactivePrincipals": 0,
          "AverageAge": 0
        },
        "CommercialActivePrincipalInformation": [
          {
            "DisplayText": "Commercial Active Principal Information",
            "DirectorID": 0000000,
            "IDNo": 0000000000000,
            "FirstName": "FIRSTNAME",
            "Initials": "F",
            "Surname": "SURNAME",
            "SecondName": "",
            "BirthDate": "YYYY-MM-DD",
            "DirectorStatusCode": "Active",
            "AppointmentDate": "YYYY-MM-DD",
            "Designation": "",
            "MemberSize": "R 0.00",
            "MemberControlPerc": 0,
            "DirectorIndicator": "YES",
            "PrincipalType": "Director",
            "CM29Date": "",
            "ISRSAResident": "Yes",
            "CountryCode": "ZA",
            "ISIDVerified": "Yes",
            "ISCIPROConfirmed": "Yes",
            "PhysicalAddress": "123 EXAMPLE STREET SUBURB CITY PROVINCE 0000",
            "PostalAddress": "123 EXAMPLE STREET SUBURB CITY PROVINCE 0000",
            "Name": "FIRSTNAME SURNAME",
            "HomeTelephoneNo": "0000000000",
            "WorkTelephoneNo": "0000000000",
            "CellularNo": "0000000000",
            "EmailAddress": "",
            "Age": "XX Years X Months",
            "YearsWithBusiness": "X Years X Months",
            "Fullname": "FIRSTNAME SECONDNAME SURNAME",
            "SurnamePrevious": "",
            "DirectorStatusDate": "YYYY-MM-DD",
            "MemberControlType": "",
            "Executor": "",
            "ExecutorAppointmentDate": "",
            "Estate": "",
            "ResignationDate": "",
            "ConsumerScore": 0,
            "PresageV3ExclusionRule": "",
            "ConsumerID": 00000000
          }
        ]
    }
}

Document history

Version	Date	Notes
1.0	2026-05-26	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: 26 May 2026

1. Overview (business)​

What these webhooks do​

How delivery works​

Where to configure subscriptions​

Event catalogue (entity domain)​

2. Shared concepts (business + technical)​

Primary key: eFICA Entity UUID​

Other identifiers​

Routing rules (important for integrations)​

Admin user fields​

Screening and validation JSON​

Payload envelope (all events)​

3. Entity record events​

3.1 entity.created​

3.2 entity.updated​

4. Entity document events​

4.1 entity.document.created​

4.2 entity.document.deleted​

5. Entity trust events (organigram)​

5.1 entityTrust.created​

5.2 entityTrust.updated​

6. UBO events​

6.1 ubo.created​

6.2 ubo.updated​

6.3 ubo.document.created / ubo.document.deleted​

7. Subscribing to entity webhooks​

Recommended starter set​

Public API example​

UI​

8. Implementation checklist (developers)​

9. Troubleshooting​

10. Entity - Mock Sample Response Data.​

10.1 AML Screening Results - no search results found.​

10.2 CIPC Search Results.​

Document history​

Support​

1. Overview (business)

What these webhooks do

How delivery works

Where to configure subscriptions

Event catalogue (entity domain)

2. Shared concepts (business + technical)

Primary key: eFICA Entity UUID

Other identifiers

Routing rules (important for integrations)

Admin user fields

Screening and validation JSON

Payload envelope (all events)

3. Entity record events

3.1 `entity.created`

3.2 `entity.updated`

4. Entity document events

4.1 `entity.document.created`

4.2 `entity.document.deleted`

5. Entity trust events (organigram)

5.1 `entityTrust.created`

5.2 `entityTrust.updated`

6. UBO events

6.1 `ubo.created`

6.2 `ubo.updated`

6.3 `ubo.document.created` / `ubo.document.deleted`

7. Subscribing to entity webhooks

Recommended starter set

Public API example

UI

8. Implementation checklist (developers)

9. Troubleshooting

10. Entity - Mock Sample Response Data.

10.1 AML Screening Results - no search results found.

10.2 CIPC Search Results.

Document history

Support