Skip to main content
API docs by Redocly

eFICA API - Public API (1.0.2)

Public OpenAPI spec for eFICA developer portal.

OAuth2

OAuth2 Authorization Endpoint

Returns HTML login form for OAuth2 authorization. User logs in and is redirected back with authorization code.

query Parameters
client_id
required
string
Example: client_id=my-client-id

OAuth2 client identifier

code_challenge
required
string
Example: code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

PKCE code challenge (base64url encoded SHA256 hash)

code_challenge_method
required
string
Value: "S256"

PKCE code challenge method (must be S256)

redirect_uri
required
string
Example: redirect_uri=https://example.com/callback

Redirect URI where authorization code will be sent

state
string
Example: state=random-state-value

Optional state parameter for CSRF protection

response_type
string
Value: "code"
Example: response_type=code

Optional response type (defaults to code)

scope
string
Example: scope=read write

Optional scope (not used in current implementation)

Responses

Response samples

Content type
application/json
{}

Process OAuth2 Login

Processes user login and redirects to redirect_uri with authorization code

Request Body schema: application/json
required
email
required
string <email>

User email address

password
required
string >= 8 characters

User password

client_id
required
string

OAuth2 client identifier

code_challenge
required
string

PKCE code challenge

code_challenge_method
required
string
Value: "S256"

PKCE code challenge method

redirect_uri
required
string

Redirect URI

state
string

Optional state parameter

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "password123",
  • "client_id": "my-client-id",
  • "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  • "code_challenge_method": "S256",
  • "redirect_uri": "https://example.com/callback",
  • "state": "random-state-value"
}

Response samples

Content type
application/json
{}

OAuth2 Token Endpoint

Exchanges authorization code for access token (PKCE required) or refreshes access token using refresh token

Request Body schema: application/json
required
grant_type
required
string
Enum: "authorization_code" "refresh_token"

Grant type (authorization_code or refresh_token)

code
string

Authorization code received from authorization endpoint (required for authorization_code grant)

code_verifier
string

PKCE code verifier (required for authorization_code grant)

redirect_uri
string

Redirect URI (required for authorization_code grant)

refresh_token
string

Refresh token (required for refresh_token grant)

client_id
required
string

OAuth2 client identifier

Responses

Request samples

Content type
application/json
{
  • "grant_type": "authorization_code",
  • "code": "abc123def456",
  • "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  • "redirect_uri": "https://example.com/callback",
  • "refresh_token": "eyJhbGciOiJFZERTQSJ9...",
  • "client_id": "my-client-id"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJFZERTQSJ9...",
  • "refresh_token": "eyJhbGciOiJFZERTQSJ9...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "userID": "123e4567-e89b-12d3-a456-426614174000",
  • "partnerID": "123e4567-e89b-12d3-a456-426614174000",
  • "scope": "read write"
}

OAuth2 Logout Endpoint

Invalidates OAuth2 session by deleting the refresh token from the database. Useful for testing and proper session management.

Request Body schema: application/json
required
refresh_token
required
string

OAuth2 refresh token to invalidate

client_id
required
string

OAuth2 client identifier

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "eyJhbGciOiJFZERTQSJ9...",
  • "client_id": "my-client-id"
}

Response samples

Content type
application/json
{
  • "message": "Logged out successfully"
}

Health & Status

Check API health status

Returns the current health status of the eFica API. This endpoint is publicly accessible and does not require authentication.

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Settings

Get countries

Retrieves a list of countries with their basic information including ISO codes, names, FATF status, and active status. Countries are used for client onboarding, risk assessment, and compliance. Returns partner-specific settings if configured, otherwise returns default system settings. The FATF flag indicates countries that require enhanced due diligence according to Financial Action Task Force guidelines.

Authorizations:
bearer
query Parameters
active
boolean
Example: active=true

Filter countries by active status. When set to true, returns only countries available for selection. When set to false, returns only inactive countries. If omitted, returns all countries regardless of status.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get employment industries

Retrieves a list of employment industries available for individual client onboarding. Each industry includes an ID, description, active status, and a flag indicating whether additional questions are required. Industries are used to categorize client employment and assess risk levels. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get entity industries

Returns a list of entity industries.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get employment types

Retrieves a list of employment types available for individual client onboarding. Each type includes an ID, description, active status, and a flag indicating whether additional questions are required. Employment types are used to categorize client employment status (e.g., Employed, Self-Employed, Retired) for risk assessment and compliance. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get individual document groups

Retrieves a list of document groups required for individual client onboarding. Document groups are parent categories (e.g., "Identity", "Proof of Address") that contain multiple document types. Each group specifies document requirements for different risk levels (low, medium, high). Use the /individual-doc-types endpoint to get specific document types within each group. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all individual document types

Retrieves all document types available for individual client onboarding. Document types are specific document variants (e.g., "RSA ID Book", "Passport", "Driver's License") that belong to document groups. Use the docID field to link document types to their parent document group from the /individual-docs endpoint. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get transaction types

Retrieves a list of transaction types used to classify and categorize client transactions. Transaction types help identify the nature of business transactions (e.g., "Annual Financial Statements", "Cash Deposits", "Wire Transfers") for compliance reporting and risk assessment. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get transaction frequencies

Retrieves a list of transaction frequency options used to describe how often transactions occur (e.g., "Monthly", "Quarterly", "Annually", "One-time"). Transaction frequencies are used to assess transaction patterns and support risk analysis. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get transaction funding sources

Retrieves a list of transaction funding sources used to describe how transactions are funded (e.g., "Bank Transfer", "Cash", "Credit Card"). Funding sources are critical for AML (Anti-Money Laundering) compliance and help identify the origin of funds. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get wealth sources

Retrieves a list of wealth sources used to describe the origin of client wealth (e.g., "Salary", "Inheritance", "Business Income", "Investment Returns"). Wealth sources are critical for Source of Wealth (SOW) and Source of Funds (SOF) compliance, particularly for high-risk clients. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get public official types

Retrieves a list of public official types used to identify Politically Exposed Persons (PEPs). PEP identification is critical for enhanced due diligence and AML (Anti-Money Laundering) compliance. Clients identified as PEPs typically require additional screening and documentation. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get custom additional questions (if enabled)

Retrieves all custom questions configured for the partner's client onboarding process. Custom questions allow partners to collect additional information beyond standard FICA requirements. These questions are partner-specific and can be configured through the partner admin interface. Questions are returned grouped by section (Individual, Trust, Entity, UBO, TrustIndividual). If none are configured, each section array is empty. This endpoint supports white-labeling and partner customization.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "sections": {
    }
}

Get entity document groups

Retrieves a list of document groups required for entity (company, trust, etc.) client onboarding. Entity document groups are parent categories (e.g., "Identity", "Registration Documents") that contain multiple document types. Each group specifies document requirements for different risk levels (low, medium, high) and includes flags for UBO (Ultimate Beneficial Owner) and trust-related party documentation. Use the /entity-doc-types endpoint to get specific document types within each group. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all entity document types

Retrieves all document types available for entity client onboarding. Document types are specific document variants (e.g., "Certificate of Incorporation", "Memorandum of Association", "Trust Deed") that belong to entity document groups. Use the docID field to link document types to their parent document group from the /entity-docs endpoint. Internal metadata fields are excluded from the response. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get entity types

Returns a list of entity types.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get trust related party types

Retrieves a list of trust related party types used to categorize parties associated with trust entities. Trust related parties include roles such as Beneficiaries, Trustees, Settlors, and Protectors. These types are used during trust onboarding to identify and document all parties involved in the trust structure for compliance purposes.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get trust Masters of the High Court

Returns a list of trust Masters of the High Court.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get trust document groups

Retrieves a list of document groups required for trust client onboarding. Trust document groups are parent categories (e.g., "Trust Deeds", "Trust Amendments") that contain multiple document types. Each group specifies document requirements for different risk levels (low, medium, high). Trust documents are specific to trust entities and are separate from entity documents. Returns partner-specific settings if configured, otherwise returns default system settings.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get partner users

Retrieves a list of users associated with the authenticated partner's account. Users are team members who have access to the partner's eFICA account. The response includes user details such as ID, role, email, name, and active status. Only users belonging to the partner associated with the OAuth2 access token are returned.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Billing

Get available balance

Returns the partner available balance (sum of non-pending/non-cancelled transactions). External partners can only query their own balance. If the partnerUUID does not match the authenticated partner, the API returns 403 Forbidden.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "balance": 1234.56
}

Additional Services

Verify an individual bank account

Runs bank account verification for the given individual using details on file (identity) and the bank details supplied in the request body. The result is stored for the eFICA application. Requires OAuth2.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

FICA individual UUID

Request Body schema: application/json
required
bankName
required
string <= 50 characters

Bank identifier as used for bureau verification (e.g. FNB, STANDARDBANK)

accountType
required
string <= 50 characters

Account type code (e.g. CURRENTCHEQUEACCOUNT, SAVINGSACCOUNT)

branchCode
required
string [ 4 .. 6 ] characters

Branch code

accountNumber
required
string [ 1 .. 13 ] characters

Account number

Responses

Request samples

Content type
application/json
{
  • "bankName": "FNB",
  • "accountType": "CURRENTCHEQUEACCOUNT",
  • "branchCode": "250655",
  • "accountNumber": "62000000000"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "bankAccountDetails": {
    },
  • "bankName": "FNB",
  • "bankAccountType": "CURRENTCHEQUEACCOUNT",
  • "bankBranchCode": "250655",
  • "bankAccountNumber": "62000000000",
  • "transactionDescription": "John Doe Bank Account Verification"
}

Individuals

List individuals with pagination and filters

Returns a paginated list of individuals for the authenticated partner. Supports filtering on multiple fields. Maximum 100 results per page.

Authorizations:
bearer
query Parameters
take
number <= 100
Example: take=50

Number of records to return (max 100)

skip
number
Example: skip=0

Number of records to skip

externalUserID
string <= 50 characters
Example: externalUserID=EXT-12345

Filter by external user ID

clientReference
string <= 50 characters
Example: clientReference=REF123456

Filter by client reference

firstName
string <= 150 characters
Example: firstName=John

Filter by first name

lastName
string <= 150 characters
Example: lastName=Doe

Filter by last name

ficaStatus
string <= 50 characters
Example: ficaStatus=Approved

Filter by FICA status

identificationNumber
string <= 50 characters
Example: identificationNumber=7510315073000

Filter by identification number

passportNumber
string <= 100 characters
Example: passportNumber=A12345678

Filter by passport number

riskDescription
string <= 50 characters
Example: riskDescription=Low Risk

Filter by risk description

approvalDate
string
Example: approvalDate=2025-12-01T00:00:00.000Z

Filter by approval date (ISO date string)

lastUpdated
string
Example: lastUpdated=2025-12-01T00:00:00.000Z

Filter by last updated date (ISO date string)

nextFicaReviewDate
string
Example: nextFicaReviewDate=2026-12-01T00:00:00.000Z

Filter by next FICA review date (ISO date string)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 150,
  • "take": 50,
  • "skip": 0
}

Create new individual record

Creates a new individual record in the ficaIndividual table and returns the individual record id as "id".

Authorizations:
bearer
Request Body schema: application/json
required
externalSystemId
string <= 50 characters

External system ID - ID from the external system

clientRef
string <= 50 characters

Client reference number

firstName
required
string <= 150 characters

First name of the individual

lastName
required
string <= 150 characters

Last name of the individual

clientEmail
required
string <email> <= 150 characters

Client email address

telNumber
required
string <= 50 characters

Client phone number

idNumber
string <= 50 characters

ID number

passportNumber
string <= 100 characters

Passport number

taxNumber
string <= 50 characters

Tax number

addressLineOne
required
string <= 150 characters

Address line one

addressLineTwo
string <= 150 characters

Address line two

townCity
required
string <= 150 characters

Town/City

zipCode
required
string <= 50 characters

ZIP code

employmentStatus
required
number

The ID of the Employment status

occupation
string <= 150 characters

Occupation

employmentIndustry
number

The clients employment industry

employerName
string <= 150 characters

The clients employer name

employerIndustry
string <= 250 characters

The industry of the clients employer

transactionFrequency
required
number

The ID of the transaction frequency

transactionType
required
number

The ID of the transaction type

transactionFundingSource
required
number

The ID of the transaction funding source

transactionSourceWealth
required
number

The ID of the transaction source of wealth

sourceFundingDescription
string <= 250 characters

Source funding description (Required if transactionSourceWealth additional questions is true).

sourceWealthDescription
string <= 250 characters

Source wealth description (Required if transactionFundingSource additional questions is true)

additionalVerification
required
boolean

Is additional verification required

additionalVerificationReason
string <= 250 characters

Additional verification reason (Only required if additionalVerification is true).

transactionConsistent
required
boolean <= 50 characters

Is the transaction consistent with your knowledge of the client.

transactionInconsistantReason
string <= 250 characters

Transaction inconsistent reason (Only required if transactionConsistent is false)

customerPermission
required
boolean

Has the customer given permission for the FICA query.

countryResidence
required
number

The ID of the clients residence country

passportCountry
required
number

The ID of the clients passport country

addressCountry
required
number

Physical address country

clientFaceToFace
required
boolean

Has the client been met Face 2 Face.

clientSACitizen
required
boolean

Is the client a South African Citizen.

object

Custom questions object

Responses

Request samples

Content type
application/json
{
  • "externalSystemId": "EXT-12345",
  • "clientRef": "REF123456",
  • "firstName": "John",
  • "lastName": "Doe",
  • "clientEmail": "john.doe@example.com",
  • "telNumber": "+27123456789",
  • "idNumber": "7510315073000",
  • "passportNumber": "A12345678",
  • "taxNumber": "1234567890",
  • "addressLineOne": "123 Main Street",
  • "addressLineTwo": "Apt 4B",
  • "townCity": "Cape Town",
  • "zipCode": "8001",
  • "employmentStatus": 5,
  • "occupation": "Software Engineer",
  • "employmentIndustry": 1,
  • "employerName": "Tech Corp",
  • "employerIndustry": "Technology",
  • "transactionFrequency": 1,
  • "transactionType": 31,
  • "transactionFundingSource": 32,
  • "transactionSourceWealth": 8,
  • "sourceFundingDescription": "Salary",
  • "sourceWealthDescription": "Savings",
  • "additionalVerification": false,
  • "additionalVerificationReason": "High risk client",
  • "transactionConsistent": true,
  • "transactionInconsistantReason": "Not applicable",
  • "customerPermission": true,
  • "countryResidence": 2,
  • "passportCountry": 0,
  • "addressCountry": 0,
  • "clientFaceToFace": true,
  • "clientSACitizen": true,
  • "customQuestions": { }
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "ficaStatus": "In Progress",
  • "riskDescription": "In Progress"
}

Get individual details by UUID

Returns individual details from the ficaIndividual table. When client validation data is available, the response includes renderVersion (V1 or V2) so the external system knows how to interpret the payload. V1: consumerDetail, kycResult, consumerEmploymentHistory at root. V2: consumerDetail and consumerAddressHistory at root (and in externalValidationData). Root-level consumerDetail is always populated when validation data exists so the same fields can be read regardless of version.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

Responses

Response samples

Content type
application/json
{
  • "riskDescription": "Low Risk"
}

Clone an existing individual details, creates new fica record.

Clones an existing individual to renew an individual if their FICA application has expired or if you need to re-FICA a client based off your internal processes. Creates a new FICA record using the source individual as the clone reference.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID - Clone source UUID

Request Body schema: application/json
required
externalSystemId
string <= 50 characters

External system ID - ID from the external system

clientRef
string <= 50 characters

Client reference number

firstName
required
string <= 150 characters

First name of the individual

lastName
required
string <= 150 characters

Last name of the individual

clientEmail
required
string <email> <= 150 characters

Client email address

telNumber
required
string <= 50 characters

Client phone number

idNumber
string <= 50 characters

ID number

passportNumber
string <= 100 characters

Passport number

taxNumber
string <= 50 characters

Tax number

addressLineOne
required
string <= 150 characters

Address line one

addressLineTwo
string <= 150 characters

Address line two

townCity
required
string <= 150 characters

Town/City

zipCode
required
string <= 50 characters

ZIP code

employmentStatus
required
number

The ID of the Employment status

occupation
string <= 150 characters

Occupation

employmentIndustry
number

The clients employment industry

employerName
string <= 150 characters

The clients employer name

employerIndustry
string <= 250 characters

The industry of the clients employer

transactionFrequency
required
number

The ID of the transaction frequency

transactionType
required
number

The ID of the transaction type

transactionFundingSource
required
number

The ID of the transaction funding source

transactionSourceWealth
required
number

The ID of the transaction source of wealth

sourceFundingDescription
string <= 250 characters

Source funding description (Required if transactionSourceWealth additional questions is true).

sourceWealthDescription
string <= 250 characters

Source wealth description (Required if transactionFundingSource additional questions is true)

additionalVerification
required
boolean

Is additional verification required

additionalVerificationReason
string <= 250 characters

Additional verification reason (Only required if additionalVerification is true).

transactionConsistent
required
boolean <= 50 characters

Is the transaction consistent with your knowledge of the client.

transactionInconsistantReason
string <= 250 characters

Transaction inconsistent reason (Only required if transactionConsistent is false)

customerPermission
required
boolean

Has the customer given permission for the FICA query.

countryResidence
required
number

The ID of the clients residence country

passportCountry
required
number

The ID of the clients passport country

addressCountry
required
number

Physical address country

clientFaceToFace
required
boolean

Has the client been met Face 2 Face.

clientSACitizen
required
boolean

Is the client a South African Citizen.

object

Custom questions object

Responses

Request samples

Content type
application/json
{
  • "externalSystemId": "EXT-12345",
  • "clientRef": "REF123456",
  • "firstName": "John",
  • "lastName": "Doe",
  • "clientEmail": "john.doe@example.com",
  • "telNumber": "+27123456789",
  • "idNumber": "7510315073000",
  • "passportNumber": "A12345678",
  • "taxNumber": "1234567890",
  • "addressLineOne": "123 Main Street",
  • "addressLineTwo": "Apt 4B",
  • "townCity": "Cape Town",
  • "zipCode": "8001",
  • "employmentStatus": 5,
  • "occupation": "Software Engineer",
  • "employmentIndustry": 1,
  • "employerName": "Tech Corp",
  • "employerIndustry": "Technology",
  • "transactionFrequency": 1,
  • "transactionType": 31,
  • "transactionFundingSource": 32,
  • "transactionSourceWealth": 8,
  • "sourceFundingDescription": "Salary",
  • "sourceWealthDescription": "Savings",
  • "additionalVerification": false,
  • "additionalVerificationReason": "High risk client",
  • "transactionConsistent": true,
  • "transactionInconsistantReason": "Not applicable",
  • "customerPermission": true,
  • "countryResidence": 2,
  • "passportCountry": 0,
  • "addressCountry": 0,
  • "clientFaceToFace": true,
  • "clientSACitizen": true,
  • "customQuestions": { }
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "ficaStatus": "In Progress",
  • "riskDescription": "In Progress"
}

Update individual details

Updates individual details based on the individual id.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

Request Body schema: application/json
required
firstName
required
string <= 150 characters

First name of the individual

lastName
required
string <= 150 characters

Last name of the individual

clientEmail
required
string <email> <= 150 characters

Client email address

clientPhone
required
string <= 50 characters

Client phone number

externalSystemId
string

External system individual record id

Responses

Request samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Doe",
  • "clientEmail": "john.doe@example.com",
  • "clientPhone": "+27123456789",
  • "externalSystemId": "889912d3-xxxx-xxxx-xxx-b77bb61231c1"
}

Response samples

Content type
application/json
{
  • "riskDescription": "Low Risk"
}

Get UBO profile image (base64)

Returns the face-match profile photo stored for the individual as base64, plus its MIME type. The image exists only after bureau verification has produced and stored a face match photo. Use faceMatchImageDocURL from create or external-validation responses to know that a photo may be available.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

Responses

Response samples

Content type
application/json
{
  • "mimeType": "image/jpeg",
  • "base64": "string"
}

Execute AML screening search

Executes an AML screening search. Uses data from the existing individual record (firstName, lastName, clientEmail).

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

Responses

Response samples

Content type
application/json
{
  • "matchedNumber": 0,
  • "matchedEntities": [ ],
  • "webSearchResults": [ ]
}

Execute external client validation

Executes a client validation search using the partner's configured verification type. Returns renderVersion V1 or V2 so the external system knows how to handle the response. V1: consumerDetail, kycResult, consumerEmploymentHistory. V2: consumerDetail, consumerAddressHistory. Validation parameters can be provided in the request body, or data from the existing individual record is used.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

Request Body schema: application/json
required
identificationNumber
string <= 50 characters

South African identification number

passportNumber
string <= 100 characters

Passport number

firstName
string <= 150 characters

First name

lastName
string <= 150 characters

Last name

residentialLine1
string <= 150 characters

Residential address line 1

residentialLine2
string <= 150 characters

Residential address line 2

residentialLine3
string <= 150 characters

Residential address line 3

residentialZIPCode
string <= 50 characters

Residential ZIP code

Responses

Request samples

Content type
application/json
{
  • "identificationNumber": "0101010000081",
  • "passportNumber": "A12345678",
  • "firstName": "John",
  • "lastName": "Doe",
  • "residentialLine1": "123 Main Street",
  • "residentialLine2": "Apt 4B",
  • "residentialLine3": "Suburb",
  • "residentialZIPCode": "2000"
}

Response samples

Content type
application/json
{
  • "renderVersion": "V1",
  • "consumerDetail": {
    },
  • "kycResult": {
    },
  • "consumerEmploymentHistory": [
    ],
  • "faceMatchResult": {
    },
  • "faceMatchImageDocURL": "uuid-key.jpg"
}

Update PEP and sanctions decision

Updates the PEP and sanctions decision for an individual.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

Request Body schema: application/json
required
pepConfirmReviewed
required
boolean

Sanctions PEP reviewed decision

adverseSearchKYC
required
boolean

Are there adverse search results?

clientForeignOfficial
required
boolean

Is the client a foreign official?

clientForeignOfficialType
number or null

The ID of the type of foreign official (Required if clientForeignOfficial is true).

Responses

Request samples

Content type
application/json
{
  • "pepConfirmReviewed": true,
  • "adverseSearchKYC": true,
  • "clientForeignOfficial": true,
  • "clientForeignOfficialType": 7
}

Response samples

Content type
application/json
{
  • "riskDescription": "Low Risk"
}

Add client document to individual record

Adds a client document and type to the fica record. Requires a file upload. Supports multiple document types and groups with a single file upload (shared document) to save storage space. Use the documents array to explicitly pair document groups (individualDocsID) with their corresponding document types (IndividualDocTypesID). Each entry in the documents array creates a separate document record, all pointing to the same uploaded file. When sending as multipart/form-data, the documents field should be a JSON string that will be automatically parsed.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

Request Body schema: multipart/form-data
required
file
required
string <binary>

Document file to upload (required)

documents
required
string

JSON string array of document group-type pairs. Each entry should have individualDocsID (number) and IndividualDocTypesID (number). Example: [{"individualDocsID": 1, "IndividualDocTypesID": 1}, {"individualDocsID": 7, "IndividualDocTypesID": 19}]

additionalFicaDoc
string

Additional FICA document flag (optional)

Responses

Response samples

Content type
application/json
{
  • "assignedGroups": [
    ],
  • "documents": [],
  • "count": 2
}

Get client document as base64

Retrieves a client document by FICA Individual Document ID and returns it as a base64 encoded string.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

ficaIndividualDocsID
required
number
Example: 123

FICA Individual Document ID

Responses

Response samples

Content type
application/json
{
  • "ficaIndividualDocsID": 123,
  • "base64Content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9MZW5ndGggND...",
  • "mimeType": "application/pdf",
  • "filename": "document.pdf"
}

Delete client document from individual record

Deletes a client document from the fica record.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

ficaIndividualDocsID
required
number
Example: 123

FICA Individual Document ID

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Confirm documents have been uploaded

Marks that documents have been uploaded and reviewed for an individual. Sets docsUploadedReviewed to true.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual fica application UUID

Request Body schema: application/json
required
userUUID
required
string <uuid>

UUID of the user who is confirming the documents

Responses

Request samples

Content type
application/json
{
  • "userUUID": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "message": "Documents confirmed successfully",
  • "docsUploadedReviewed": true
}

Update onboarding decision

Updates the onboarding decision for an individual.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

Request Body schema: application/json
required
onboardingDecision
required
string <= 50 characters
Enum: "Approved" "Declined" "Refer" "In Progress"

Client onboarding decision

additionalComments
string <= 250 characters

Transaction approve, decline, refer reason

nextFicaReviewDate
string <= 250 characters

Date of fica expiry.

Responses

Request samples

Content type
application/json
{
  • "onboardingDecision": "Approved",
  • "additionalComments": "All checks passed",
  • "nextFicaReviewDate": "2025-12-02T22:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "message": "The client was successfully onboarded."
}

Get PDF report of FICA application

Generates the PDF report of the FICA application. By default returns JSON with a base64-encoded string. Use format=binary to receive raw application/pdf bytes (e.g. for large files). The report includes personal information, addresses, employment details, compliance questionnaire, and verification checks.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The individual UUID

query Parameters
format
string
Enum: "json" "binary"

Omit or use json for { base64Content, mimeType, filename }. Use binary for raw PDF body.

Responses

Response samples

Content type
{
  • "base64Content": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9DYXRhbG9nCi9QYWdlcyAyIDAgUgo+PgplbmRvYmoK...",
  • "mimeType": "application/pdf",
  • "filename": "fica-report-123e4567-e89b-12d3-a456-426614174000.pdf"
}

Entities

List entities with pagination and filters

Returns a paginated list of entities for the authenticated partner. Supports filtering on multiple fields. Maximum 100 results per page.

Authorizations:
bearer
query Parameters
take
number <= 100
Example: take=50

Number of records to return (max 100)

skip
number
Example: skip=0

Number of records to skip

externalUserID
string <= 50 characters
Example: externalUserID=EXT-12345

Filter by external user ID

clientReference
string <= 50 characters
Example: clientReference=REF123456

Filter by client reference

ficaStatus
string <= 50 characters
Example: ficaStatus=Approved

Filter by FICA status

riskDescription
string <= 50 characters
Example: riskDescription=Low Risk

Filter by risk description

approvalDate
string
Example: approvalDate=2025-12-01T00:00:00.000Z

Filter by approval date (ISO date string)

lastUpdated
string
Example: lastUpdated=2025-12-01T00:00:00.000Z

Filter by last updated date (ISO date string)

nextFicaReviewDate
string
Example: nextFicaReviewDate=2026-12-01T00:00:00.000Z

Filter by next FICA review date (ISO date string)

Responses

Response samples

Content type
application/json
{ }

Create a new entity record

Creates an entity record from CIPC registration details. Returns enriched CIPC commercial data, sanctions screening results, and any UBO records created from CIPC principal information.

Authorizations:
bearer
Request Body schema: application/json
required
externalSystemId
string <= 50 characters

External system identifier for this entity in your system

clientReference
string <= 50 characters

Partner client reference

entityRegNumber
required
string <= 150 characters

Company registration number (CIPC format)

entityType
required
integer

Entity type ID from settings entity-types

entityRegName
required
string <= 150 characters

Registered entity name

Responses

Request samples

Content type
application/json
{
  • "externalSystemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "clientReference": "REF-001",
  • "entityRegNumber": "2020/123456/07",
  • "entityType": 1,
  • "entityRegName": "EXAMPLE ENTITY (PTY) LTD"
}

Response samples

Content type
application/json
{
  • "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "adminAdded": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  • "adminAddedDate": "2026-06-01T10:00:00.000Z",
  • "entityAddressLine1": "123 Example Street",
  • "entityAddressLine2": "Example Suburb",
  • "entityAddressLine3": "Example City",
  • "entityZIPCode": "EXAMPLE PROVINCE",
  • "entityRegName": "EXAMPLE ENTITY (PTY) LTD",
  • "entityRegNumber": "2020/123456/07",
  • "clientReference": "REF-001",
  • "physicalAddress": "123 Example Street, Example Suburb, Example City, EXAMPLE PROVINCE, 0001",
  • "postalAddress": "123 Example Street, Example Suburb, Example City, EXAMPLE PROVINCE, 0001",
  • "ficaStatus": "In Progress",
  • "riskDescription": "Undetermined",
  • "transactionFrequency": 1,
  • "cipcCommercialName": "EXAMPLE GAMING (PTY) LTD",
  • "cipcCommercialResponse": {
    },
  • "sanctionsSearchResults": {
    },
  • "createdUbos": [
    ]
}

Update the external system ID of an entity to eFICA

Update the external system ID of an entity to eFICA.

Authorizations:
bearer
Request Body schema: application/json
required
id
required
string <uuid> <= 50 characters

eFICA entity UUID

externalSystemId
required
string <= 50 characters

External system identifier for this entity in your system

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "externalSystemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response samples

Content type
application/json
{
  • "success": true
}

Update Entity KYB details

Updates entity KYB (Know Your Business) details from the external system, including trading name, address, industry, transaction profile, compliance flags, and custom form answers.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

FICA entity UUID

Request Body schema: application/json
required
sameEntityName
required
boolean

Whether the trading name is the same as the registered name

entityTradingName
required
string <= 150 characters

Entity trading name

entityTelNumber
required
string [ 10 .. 15 ] characters

Entity telephone number

physicalAddress1
required
string <= 150 characters

Physical address line 1

physicalAddress2
required
string <= 150 characters

Physical address line 2

physicalAddress3
required
string <= 150 characters

Physical address line 3

zipCode
required
string <= 20 characters

Postal code or province label

addressCountry
required
integer

Address country ID from settings countries

countriesTransactedWith
required
Array of integers

Country IDs the entity transacts with

entityIndustry
required
integer

Entity industry ID from settings

entityIndustryDescription
string <= 150 characters

Industry description when industry is Other

transactionFrequency
required
integer

Transaction frequency ID

transactionType
required
integer

Transaction type ID

transactionFundingSource
required
integer

Transaction funding source ID

sourceFundingDescription
string <= 150 characters

Funding source description when source is Other

transactionSourceWealth
required
integer

Source of wealth ID

sourceWealthDescription
string <= 150 characters

Source of wealth description when source is Other

additionalVerification
required
boolean

Whether additional verification is required

additionalVerificationReason
string <= 250 characters

Reason for additional verification

transactionConsistent
required
string <= 5 characters

Whether the transaction is consistent with the client profile

transactionInconsistantReason
string <= 150 characters

Reason when the transaction is not consistent

entityDetailsConfirmed
required
boolean

Whether entity KYB details have been confirmed

object

Partner custom form question answers keyed by question ID

userID
required
string <uuid>

eFICA user UUID performing the update (must belong to the partner)

Responses

Request samples

Content type
application/json
{
  • "sameEntityName": true,
  • "entityTradingName": "Example Entity (Pty) Ltd",
  • "entityTelNumber": "0215558888",
  • "physicalAddress1": "123 Example Street",
  • "physicalAddress2": "Example Suburb",
  • "physicalAddress3": "Example City",
  • "zipCode": "EXAMPLE PROVINCE",
  • "addressCountry": 189,
  • "countriesTransactedWith": [
    ],
  • "entityIndustry": 2,
  • "entityIndustryDescription": "",
  • "transactionFrequency": 1,
  • "transactionType": 31,
  • "transactionFundingSource": 31,
  • "sourceFundingDescription": "",
  • "transactionSourceWealth": 6,
  • "sourceWealthDescription": "",
  • "additionalVerification": false,
  • "additionalVerificationReason": "",
  • "transactionConsistent": "true",
  • "transactionInconsistantReason": "",
  • "entityDetailsConfirmed": true,
  • "customQuestions": { },
  • "userID": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

Response samples

Content type
application/json
{
  • "success": true
}

Confirm Entity & KYB Sanctions

Confirms entity KYB sanctions and adverse media review outcomes from the external system. Records whether adverse KYC search and PEP/sanctions list review have been completed.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

FICA entity UUID

Request Body schema: application/json
required
adverseSearchKYC
required
boolean

Whether adverse KYC search results apply to the entity

pepConfirmReviewed
required
boolean

Whether PEP and sanctions list review has been confirmed

Responses

Request samples

Content type
application/json
{
  • "adverseSearchKYC": false,
  • "pepConfirmReviewed": true
}

Response samples

Content type
application/json
{
  • "success": true
}

Create director or UBO

Creates a new director or UBO on an existing entity. Runs sanctions screening and, for South African citizens with an ID number, bureau verification including face match. The UBO is created even if external verification is temporarily unavailable; verification fields are omitted from the response when searches did not run.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

FICA entity UUID

Request Body schema: application/json
required
externalId
string <= 50 characters

External system identifier for this director/UBO in your system

firstName
required
string <= 150 characters

First name

lastName
required
string <= 150 characters

Last name

addressLine1
required
string <= 100 characters

Residential address line 1

addressLine2
required
string <= 100 characters

Residential address line 2

addressLine3
required
string <= 100 characters

Residential address line 3

addressZipCode
required
string <= 20 characters

Residential postal or ZIP code

addressCountry
required
integer

Residential country ID (countries table)

clientSACitizen
required
boolean
Default: false

Whether the director/UBO is a South African citizen

idNumber
string or null <= 13 characters

South African ID number (required when clientSACitizen is true)

passportCountry
integer or null

Passport issuing country ID (countries table)

passportNumber
string or null <= 50 characters

Passport number (required when clientSACitizen is false)

resolutionToAct
boolean or null

Whether a resolution to act is on file

isShareholder
required
boolean
Default: false

Whether this person is a shareholder

shareholderPercentage
required
string <= 20 characters
Default: "0"

Shareholder percentage as a string (e.g. "0", "25.5")

object

Partner custom form answers keyed by question ID (object) or pre-stringified JSON string

isDirector
required
boolean
Default: false

Whether this person is a director

informationConfirmed
required
boolean
Default: false

Whether the director/UBO information has been confirmed

trustRelatedPartyTypes
string (PublicVerifyEntityOrganigramTrustRelatedPartyTypes)

Trust relationship type(s) for an Individual who is a direct child of a Trust node in the organigram tree. Stored on uboLink.trustRelatedPartyTypes (not on the UBO row). Where to send: on each Individual node nested under a Trust node's children array during verify-organigram. Not read from root.ubos[] or root.trustUbos[].relatedParties[]. Format: a JSON string containing a stringified array of PublicVerifyEntityOrganigramTrustRelatedPartyTypeEntry objects. Do not send a raw JSON array — the value must be a string (same format the efica UI submits). Lookup valid id / name pairs via GET /api/v1/settings/trust-related-party-types.

Responses

Request samples

Content type
application/json
{
  • "externalId": "ext-ubo-001",
  • "firstName": "Alex",
  • "lastName": "Sample",
  • "addressLine1": "100 Example Street",
  • "addressLine2": "Example Suburb",
  • "addressLine3": "Example City",
  • "addressZipCode": "8001",
  • "addressCountry": 189,
  • "clientSACitizen": true,
  • "idNumber": "8001015009087",
  • "resolutionToAct": true,
  • "isShareholder": false,
  • "shareholderPercentage": "0",
  • "customQuestionsAnswers": {
    },
  • "isDirector": true,
  • "informationConfirmed": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  • "sanctionsSearchResults": {
    },
  • "renderVersion": "V1",
  • "consumerDetail": {
    },
  • "kycResult": {
    },
  • "faceMatchResult": {
    },
  • "faceMatchImageDocURL": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11.jpg"
}

Update director or UBO

Updates an existing director or UBO. Path id is the UBO UUID. Uses the same request body as create. Sanctions and bureau verification run only when results are not already stored on the UBO; returned verification fields match the create response. Trust relationship types: Trust-member UBOs (those with ficaEntityTrustID on the UBO record, set during verify-organigram) may include optional trustRelatedPartyTypes in the body to create or update uboLink.trustRelatedPartyTypes. Same JSON-string format as verify-organigram. Omit for entity-level UBOs that are not trust members. The entity organigram is refreshed after update so relationship badges stay in sync in efica.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

The UBO UUID

Request Body schema: application/json
required
externalId
string <= 50 characters

External system identifier for this director/UBO in your system

firstName
required
string <= 150 characters

First name

lastName
required
string <= 150 characters

Last name

addressLine1
required
string <= 100 characters

Residential address line 1

addressLine2
required
string <= 100 characters

Residential address line 2

addressLine3
required
string <= 100 characters

Residential address line 3

addressZipCode
required
string <= 20 characters

Residential postal or ZIP code

addressCountry
required
integer

Residential country ID (countries table)

clientSACitizen
required
boolean
Default: false

Whether the director/UBO is a South African citizen

idNumber
string or null <= 13 characters

South African ID number (required when clientSACitizen is true)

passportCountry
integer or null

Passport issuing country ID (countries table)

passportNumber
string or null <= 50 characters

Passport number (required when clientSACitizen is false)

resolutionToAct
boolean or null

Whether a resolution to act is on file

isShareholder
required
boolean
Default: false

Whether this person is a shareholder

shareholderPercentage
required
string <= 20 characters
Default: "0"

Shareholder percentage as a string (e.g. "0", "25.5")

object

Partner custom form answers keyed by question ID (object) or pre-stringified JSON string

isDirector
required
boolean
Default: false

Whether this person is a director

informationConfirmed
required
boolean
Default: false

Whether the director/UBO information has been confirmed

trustRelatedPartyTypes
string (PublicVerifyEntityOrganigramTrustRelatedPartyTypes)

Trust relationship type(s) for an Individual who is a direct child of a Trust node in the organigram tree. Stored on uboLink.trustRelatedPartyTypes (not on the UBO row). Where to send: on each Individual node nested under a Trust node's children array during verify-organigram. Not read from root.ubos[] or root.trustUbos[].relatedParties[]. Format: a JSON string containing a stringified array of PublicVerifyEntityOrganigramTrustRelatedPartyTypeEntry objects. Do not send a raw JSON array — the value must be a string (same format the efica UI submits). Lookup valid id / name pairs via GET /api/v1/settings/trust-related-party-types.

Responses

Request samples

Content type
application/json
{
  • "externalId": "ext-ubo-001",
  • "firstName": "Alex",
  • "lastName": "Sample",
  • "addressLine1": "100 Example Street",
  • "addressLine2": "Example Suburb",
  • "addressLine3": "Example City",
  • "addressZipCode": "8001",
  • "addressCountry": 189,
  • "clientSACitizen": true,
  • "idNumber": "8001015009087",
  • "resolutionToAct": true,
  • "isShareholder": false,
  • "shareholderPercentage": "0",
  • "customQuestionsAnswers": {
    },
  • "isDirector": true,
  • "informationConfirmed": true,
  • "trustRelatedPartyTypes": "[{\"id\":1,\"name\":\"Founder\"},{\"id\":2,\"name\":\"Trustees\"}]"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  • "sanctionsSearchResults": {
    },
  • "consumerDetail": {
    },
  • "kycResult": {
    },
  • "faceMatchResult": {
    },
  • "faceMatchImageDocURL": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11.jpg"
}

Get UBO profile image (base64)

Returns the face-match profile photo stored for the director or UBO as base64, plus its MIME type. Requires OAuth2. The image exists only after bureau verification has produced and stored a face match photo. Use faceMatchImageDocURL from the create director or UBO response to know that a photo may be available.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

The UBO UUID

Responses

Response samples

Content type
application/json
{
  • "mimeType": "image/jpeg",
  • "base64": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCwAA8A/9k="
}

Confirm UBO PEP and sanctions review

Updates adverse KYC and PEP/sanctions review on a UBO (path id is the UBO UUID), recalculates UBO risk using the same rules as internal step-two confirmation, and returns riskStatus and riskReason.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

The UBO UUID

Request Body schema: application/json
required
adverseSearchKYC
required
boolean

Whether adverse KYC search results apply to the UBO

pepConfirmReviewed
required
boolean

Whether PEP and sanctions list review has been confirmed

Responses

Request samples

Content type
application/json
{
  • "adverseSearchKYC": false,
  • "pepConfirmReviewed": true
}

Response samples

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

Add client document to UBO record

Uploads one document for a UBO (path id is uboUUID). Multipart fields: file (required) and documents (required) as a single JSON object { individualDocsID, IndividualDocTypesID }, or a JSON array with exactly one such object. Multiple document groups or types in one request return 400.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

The UBO UUID

Request Body schema: multipart/form-data
required
file
required
string <binary>

Document file to upload (required)

documents
required
string

JSON object or single-element array with individualDocsID (number) and IndividualDocTypesID (number). Only one group and type per upload.

additionalFicaDoc
string <= 5 characters

Additional FICA document flag (optional)

Responses

Response samples

Content type
application/json
{
  • "uboDocsID": 456
}

Get UBO document as base64

Retrieves a UBO document by uboDocsID (path id) and returns the file as base64. Partner-scoped via the parent UBO's entity.

Authorizations:
bearer
path Parameters
id
required
integer
Example: 123

UBO document ID (uboDocsID)

Responses

Response samples

Content type
application/json
{
  • "uboDocsID": 123,
  • "base64Content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9MZW5ndGggND...",
  • "mimeType": "application/pdf",
  • "filename": "document.pdf"
}

Delete client document from UBO record

Deletes a UBO document by uboDocsID (path id).

Authorizations:
bearer
path Parameters
id
required
integer
Example: 123

UBO document ID (uboDocsID)

Responses

Response samples

Content type
application/json
{
  • "result": {
    }
}

Confirm UBO documents have been uploaded

Confirms UBO document upload/review status. Path id is the UBO UUID. Request body supplies docsUploadedReviewed (boolean), which is persisted on the UBO record.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

The UBO UUID

Request Body schema: application/json
required
docsUploadedReviewed
required
boolean

Whether UBO documents have been uploaded and reviewed

Responses

Request samples

Content type
application/json
{
  • "docsUploadedReviewed": true
}

Response samples

Content type
application/json
{
  • "message": "Documents confirmed successfully"
}

Confirm entity shareholding / ownership structure

Confirms entity shareholding / ownership structure review. Request body supplies ownershipConfirmation (boolean), persisted as ownershipStructureReviewed on the entity. Recalculates entity risk and returns riskStatus and riskReason.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The entity UUID

Request Body schema: application/json
required
ownershipConfirmation
required
boolean

Ownership / shareholding structure confirmation

Responses

Request samples

Content type
application/json
{
  • "ownershipConfirmation": true
}

Response samples

Content type
application/json
{
  • "message": "Shareholding confirmed successfully",
  • "riskStatus": "Low Risk",
  • "riskReason": "The entities calculated risk score (5) is within the low risk range. (1 to 14)"
}

Verify and build entity organigram

Verifies / builds the entity ownership structure from the supplied organigram. Path id is the entity UUID. The request body supplies entityOrganigram as a JSON array. The endpoint creates trusts (Entity Trust), creates or updates UBOs (an existing UBO is identified by its uboID, a null uboID creates a new UBO) and their trust related-party links (uboLink), and finalises the ownership structure (ownershipStructureReviewed, directorsListChecked, shareholdersConfirmed). Trust relationship types: For each Individual node that is a direct child of a Trust node, include trustRelatedPartyTypes (see schema). This is stored and drives the relationship typein eFica. Lookup valid type IDs and labels via GET /api/v1/settings/trust-related-party-types. Returns the processed organigram in the external-system shape, plus the entity riskStatus and riskDescription.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The entity UUID

Request Body schema: application/json
required
required
Array of objects (PublicVerifyEntityOrganigramNode)

The entity organigram value. Provided as a JSON array whose first node must be Root. efica stringifies this when storing on ficaEntity.entityOrganigram.

Array
guid
string <uuid>

Stable identifier for this node in the external system.

shareholderType
string <= 20 characters
Enum: "Root" "Individual" "Trust" "Entity"

Node type in the ownership structure.

uboID
string or null <uuid>

For Individual nodes: existing uboUUID when updating; null to create a new UBO.

firstName
string <= 150 characters

Individual first name.

lastName
string <= 150 characters

Individual last name.

shareholderEntityName
string <= 150 characters

Registered entity name when shareholderType is Entity.

shareholderTrustName
string <= 150 characters

Trust name when shareholderType is Trust.

shareholderPercentage
number

Shareholding percentage at this level of the tree.

uboPercentage
number

Effective UBO percentage for this node.

isDirector
boolean

Whether this Individual is a director.

isTrustMember
boolean

Whether this Individual is a member of the parent Trust (informational).

hasResolution
string <= 5 characters

String boolean — whether a resolution to act is on file.

parentGUID
string <uuid>

GUID of the parent node in the tree.

trustRelatedPartyTypes
string (PublicVerifyEntityOrganigramTrustRelatedPartyTypes)

Trust relationship type(s) for an Individual who is a direct child of a Trust node in the organigram tree. Stored on uboLink.trustRelatedPartyTypes (not on the UBO row). Where to send: on each Individual node nested under a Trust node's children array during verify-organigram. Not read from root.ubos[] or root.trustUbos[].relatedParties[]. Format: a JSON string containing a stringified array of PublicVerifyEntityOrganigramTrustRelatedPartyTypeEntry objects. Do not send a raw JSON array — the value must be a string (same format the efica UI submits). Lookup valid id / name pairs via GET /api/v1/settings/trust-related-party-types.

children
Array of objects (PublicVerifyEntityOrganigramNode)

Child nodes in the ownership structure.

Array of objects

Entity-level UBO summary list on the Root node (percentages keyed by child guid). efica rebuilds this from the database after processing.

Array of objects

Trust summary list on the Root node. efica rebuilds relatedParties from the database after processing; incoming relatedParties are not used as the source of truth.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "entityOrganigram": [
    ]
}

Response samples

Content type
application/json
{
  • "entityOrganigram": [
    ],
  • "riskStatus": "High Risk",
  • "riskDescription": "The entities risk score (19) equals or exceeds the high risk threshold score (15)."
}

Get entity document as base64

Retrieves an entity document by entityDocID (path id) and returns the file as base64. Partner-scoped via the parent entity.

Authorizations:
bearer
path Parameters
id
required
integer
Example: 123

Entity document ID (entityDocID)

Responses

Response samples

Content type
application/json
{
  • "entityDocID": 123,
  • "base64Content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9MZW5ndGggND...",
  • "mimeType": "application/pdf",
  • "filename": "document.pdf"
}

Upload entity document

Uploads one document for an entity. Multipart fields: file (required) and documents (required) as a single JSON object { entityDocsID, entityDocTypesID }, or a JSON array with exactly one such object. Multiple document groups or types in one request return 400.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The entity UUID

Request Body schema: multipart/form-data
required
file
required
string <binary>

Document file to upload (required)

documents
required
string

JSON object or single-element array with entityDocsID (number) and entityDocTypesID (number). Only one group and type per upload.

additionalFicaDoc
string <= 5 characters

Additional FICA document flag (optional)

Responses

Response samples

Content type
application/json
{
  • "entityDocID": 123
}

Delete entity document

Deletes an entity document by entityDocID (path id). Partner-scoped via the parent entity.

Authorizations:
bearer
path Parameters
id
required
integer
Example: 123

Entity document ID (entityDocID)

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Confirm entity documents have been uploaded

Confirms entity document upload/review status. Request body supplies docsUploadedReviewed (boolean), persisted on the entity record.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: ceac5f5e-9dea-4b47-927d-1ed39ab10e43

The entity UUID

Request Body schema: application/json
required
docsUploadedReviewed
required
boolean

Whether entity documents have been uploaded and reviewed

Responses

Request samples

Content type
application/json
{
  • "docsUploadedReviewed": true
}

Response samples

Content type
application/json
{
  • "message": "Documents confirmed successfully"
}

Update entity onboarding decision

Updates entity onboarding decision and decision-specific comments. Rejected with 403 if the entity is already Approved or Declined. Admin IDs and dates are set from the OAuth2 token user (not the request body).

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: ceac5f5e-9dea-4b47-927d-1ed39ab10e43

The entity UUID

Request Body schema: application/json
required
onboardingDecision
required
string <= 50 characters
Enum: "Approved" "Declined" "Refer" "In Progress"

Entity onboarding decision

nextFicaReviewDate
string <date-time>

Next FICA review date (optional; omitted leaves existing value unchanged)

referComments
string <= 250 characters

Required when onboardingDecision is Refer (maps to referredToAdminReason)

approvedComments
string <= 250 characters

Optional when onboardingDecision is Approved

declinedComments
string <= 250 characters

Required when onboardingDecision is Declined

Responses

Request samples

Content type
application/json
{
  • "onboardingDecision": "Approved",
  • "nextFicaReviewDate": "2027-06-02T00:00:00.000Z",
  • "approvedComments": "All checks passed"
}

Response samples

Content type
application/json
{
  • "riskDescription": "Low Risk"
}

Get entity PDF FICA report

Generates the PDF report of the entity FICA application. By default returns JSON with a base64-encoded string. Use format=binary to receive raw application/pdf bytes (e.g. for large files). The report includes entity details, directors and UBOs, compliance questionnaire, verification checks, and risk audit.

Authorizations:
bearer
path Parameters
id
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The entity UUID

query Parameters
format
string
Enum: "json" "binary"

Omit or use json for { base64Content, mimeType, filename }. Use binary for raw PDF body.

Responses

Response samples

Content type
{
  • "base64Content": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9DYXRhbG9nCi9QYWdlcyAyIDAgUgo+PgplbmRvYmoK...",
  • "mimeType": "application/pdf",
  • "filename": "fica-report-123e4567-e89b-12d3-a456-426614174000.pdf"
}