Settings

Overview

Settings endpoints return reference data (for example, dropdown lists) used during onboarding and verification flows.

eFICA Settings Guide

Table of Contents

1. Overview
2. Authentication
3. Base URLs
4. Geographic & Reference Data
5. Document Settings
6. Transaction Settings
7. Compliance & Additional Settings
8. Error Handling
9. Best Practices
10. Quick Reference

---

Overview

The eFICA Settings API provides access to system configuration data and reference information used throughout the FICA (Financial Intelligence Centre Act) client onboarding process. These endpoints return partner-specific settings when configured, otherwise default system settings are provided.

Key Features

• Geographic & Reference Data: Countries, industries, employment types, and entity classifications
• Document Configuration: Document groups and types for individuals, entities, and trusts with risk-level requirements
• Transaction Settings: Transaction types, frequencies, and funding sources for compliance reporting
• Compliance Data: Wealth sources, public official types (PEP), and trust-related party classifications
• Partner Customization: Custom questions and user management for white-labeling
• Partner-Specific: All responses are automatically filtered by your partner account
• Read-Only: All endpoints are GET requests for retrieving configuration data

Use Cases

• Form Population: Populate dropdown lists and form fields in client onboarding applications
• Document Requirements: Determine which documents are required based on risk levels (low/medium/high) and client types
• Compliance Workflows: Support AML (Anti-Money Laundering), PEP screening, and Source of Wealth (SOW) compliance
• Transaction Classification: Configure transaction options for client onboarding and reporting
• Partner Customization: Retrieve partner-specific custom questions for white-labeling
• User Management: Get list of partner users for assignment and workflow purposes

Understanding Risk Levels

Document requirements vary by risk level:

• Low Risk: Standard document requirements (e.g., "Copy of ID Document")
• Medium Risk: Enhanced document requirements (e.g., "Copy of ID Document - original sighted")
• High Risk: Strictest requirements (e.g., "Copy of ID Document original sighted" or "Certified copy")

Document Hierarchy

Understanding the relationship between document groups and types:

• Document Groups: Parent categories (e.g., "Identity", "Proof of Address") that contain multiple document types
• Document Types: Specific document variants within groups (e.g., "RSA ID Book", "Passport", "Driver's License")
• Linking: Use the docID or entityDocsID field in document types to link them to their parent document group

---

Authentication

All endpoints require OAuth2 Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-oauth2-token>

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

Important:

• All responses are automatically filtered by your partner account
• You can only access settings for your own partner
• Tokens expire after 1 hour - use refresh tokens to obtain new access tokens

---

Base URLs

• Sandbox: https://sandboxapi.efica.co.za
• Production: https://loginapi.efica.co.za

API Version

All endpoints are under /api/v1/settings

---

Geographic & Reference Data

Get Countries

Retrieve 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. The FATF (Financial Action Task Force) flag indicates countries that require enhanced due diligence.

Endpoint: GET /api/v1/settings/countries

Query Parameters:

Parameter	Type	Required	Description
isActive	boolean	No	Filter 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.

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/countries?isActive=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "id": 1,
    "code": "ZA",
    "name": "South Africa",
    "fatf": false,
    "active": true
  },
  {
    "id": 118,
    "code": "VI",
    "name": "U.S. Virgin Islands",
    "fatf": false,
    "active": true
  },
  {
    "id": 103,
    "code": "IM",
    "name": "Isle of Man",
    "fatf": true,
    "active": true
  }
]

Response Fields:

• id (number): Unique identifier for the country
• code (string): ISO country code (e.g., "ZA", "VI", "IM")
• name (string): Full country name
• fatf (boolean): Whether the country is on the FATF (Financial Action Task Force) list. FATF countries require enhanced due diligence.
• active (boolean): Whether the country is active and available for selection

Use Cases:

• Populate country dropdowns in client registration forms
• Filter countries by active status for user selection
• Display country information for compliance purposes
• Identify FATF countries that require enhanced due diligence

Note: Returns partner-specific country settings if configured, otherwise returns default system settings.

---

Get Employment Industries

Retrieve a list of employment industries available for individual client onboarding. Industries are used to categorize client employment and assess risk levels. Each industry includes an ID, description, active status, and a flag indicating whether additional questions are required.

Endpoint: GET /api/v1/settings/employment-industries

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/employment-industries" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "id": 1,
    "name": "Agriculture, forestry and fishing",
    "active": true,
    "additionalQuestions": false
  },
  {
    "id": 14,
    "name": "Activities of religious, political and extraterritorial organisations/bodies",
    "active": true,
    "additionalQuestions": true
  },
  {
    "id": 20,
    "name": "Manufacturing",
    "active": true,
    "additionalQuestions": false
  }
]

Response Fields:

• id (number): Unique identifier for the industry
• name (string): Description of the employment industry
• active (boolean): Whether the industry is active
• additionalQuestions (boolean): Whether additional questions are required when this industry is selected. When true, you should prompt users for additional information.

Use Cases:

• Populate industry dropdowns in individual client registration forms
• Determine if additional questions are required based on industry risk
• Support risk assessment and compliance workflows

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Employment Types

Retrieve a list of employment types available for individual client onboarding. Employment types are used to categorize client employment status (e.g., Employed, Self-Employed, Retired) for risk assessment and compliance.

Endpoint: GET /api/v1/settings/employment-types

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/employment-types" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "id": 1,
    "name": "Employed",
    "active": true,
    "additionalQuestions": false
  },
  {
    "id": 2,
    "name": "Self-Employed",
    "active": true,
    "additionalQuestions": true
  },
  {
    "id": 4,
    "name": "Retired",
    "active": true,
    "additionalQuestions": false
  },
  {
    "id": 5,
    "name": "Unemployed",
    "active": true,
    "additionalQuestions": true
  }
]

Response Fields:

• id (number): Unique identifier for the employment type
• name (string): Description of the employment type
• active (boolean): Whether the type is active
• additionalQuestions (boolean): Whether additional questions are required when this type is selected

Use Cases:

• Populate employment type dropdowns in individual client forms
• Determine if additional questions are required based on employment status
• Support income verification and risk assessment processes

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Entity Industries

Retrieve a list of industries available for entity (company, trust, etc.) client onboarding. Entity industries are used to categorize business entities and assess risk levels.

Endpoint: GET /api/v1/settings/entity-industries

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/entity-industries" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "id": 1,
    "name": "Extraction of crude petroleum, natural gas",
    "active": true,
    "additionalQuestions": false
  },
  {
    "id": 2,
    "name": "Financial service activities, except insurance and pension funding",
    "active": true,
    "additionalQuestions": true
  },
  {
    "id": 3,
    "name": "Real estate activities",
    "active": true,
    "additionalQuestions": false
  }
]

Response Fields:

• id (number): Unique identifier for the entity industry
• name (string): Description of the entity industry
• active (boolean): Whether the industry is active
• additionalQuestions (boolean): Whether additional questions are required

Use Cases:

• Populate industry dropdowns in entity registration forms
• Determine risk levels and compliance requirements based on industry
• Support entity onboarding workflows

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Entity Types

Retrieve a list of entity types (legal structures) available for entity client onboarding. Entity types define the legal structure of business entities (e.g., "Close Corporation (CC)", "Private Company", "Trust", "Partnership"). Each type includes flags indicating whether additional questions are required and whether an organigram (organizational chart) must be provided.

Endpoint: GET /api/v1/settings/entity-types

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/entity-types" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "EntityTypeID": 5,
    "EntityTypeDesc": "Close Corporation- CC",
    "IsActive": true,
    "RequireAdditionalQuestions": false,
    "showOrganigram": false
  },
  {
    "EntityTypeID": 6,
    "EntityTypeDesc": "Private Company",
    "IsActive": true,
    "RequireAdditionalQuestions": false,
    "showOrganigram": true
  },
  {
    "EntityTypeID": 7,
    "EntityTypeDesc": "Trust",
    "IsActive": true,
    "RequireAdditionalQuestions": true,
    "showOrganigram": true
  }
]

Response Fields:

• EntityTypeID (number): Unique identifier for the entity type
• EntityTypeDesc (string): Description of the entity type
• IsActive (boolean): Whether the type is active
• RequireAdditionalQuestions (boolean): Whether additional questions are required
• showOrganigram (boolean): Whether to show organizational chart functionality for this entity type

Use Cases:

• Populate entity type dropdowns in entity registration forms
• Determine if additional questions are required based on entity type
• Control whether organigram (organizational chart) is required
• Support entity onboarding workflows

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Document Settings

Understanding Document Structure

Documents in the eFICA system follow a two-level hierarchy:

1. Document Groups: Parent categories (e.g., "Identity", "Proof of Address", "Trust Deeds")

   • Define document requirements by risk level (low, medium, high)
   • Contain multiple document types
   • Retrieved from endpoints like /individual-docs, /entity-docs, /trust-docs

2. Document Types: Specific document variants within groups (e.g., "RSA ID Book", "Passport", "Certificate of Incorporation")

   • Belong to a document group (linked via docID or entityDocsID)
   • Retrieved from endpoints like /individual-doc-types, /entity-doc-types

Important: When uploading documents, you need both:

• The document group ID (e.g., individualDocsID, entityDocsID)
• The document type ID (e.g., IndividualDocTypesID, EntityDocTypesID)

---

Get Individual Document Groups

Retrieve 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).

Endpoint: GET /api/v1/settings/individual-docs

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/individual-docs" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "id": 1,
    "name": "Identity",
    "lowRiskRequired": true,
    "lowRiskDescription": "Copy of ID Document",
    "mediumRiskRequired": true,
    "mediumRiskDescription": "Copy of ID Document",
    "highRiskRequired": true,
    "highRiskDescription": "Copy of ID Document original sighted",
    "description": "ID Number given by Client corresponds to ID number on documentation",
    "active": true
  },
  {
    "id": 2,
    "name": "Proof of Address",
    "lowRiskRequired": true,
    "lowRiskDescription": "Utility bill or bank statement (not older than 3 months)",
    "mediumRiskRequired": true,
    "mediumRiskDescription": "Utility bill or bank statement (not older than 3 months) - original sighted",
    "highRiskRequired": true,
    "highRiskDescription": "Utility bill or bank statement (not older than 3 months) - certified copy",
    "description": "Proof of residential address must be current and verifiable",
    "active": true
  }
]

Response Fields:

• id (number): Unique identifier for the document group (use as individualDocsID when uploading documents)
• name (string): Name of the document group (e.g., "Identity", "Proof of Address")
• lowRiskRequired (boolean): Whether required for low-risk clients
• lowRiskDescription (string): Document requirement description for low-risk clients
• mediumRiskRequired (boolean): Whether required for medium-risk clients
• mediumRiskDescription (string): Document requirement description for medium-risk clients
• highRiskRequired (boolean): Whether required for high-risk clients
• highRiskDescription (string): Document requirement description for high-risk clients
• description (string): Description of what to check/verify for this document
• active (boolean): Whether the document setting is active

Use Cases:

• Display required document categories in client onboarding forms
• Determine document requirements based on risk level (low/medium/high)
• Guide clients through the document collection process

Next Step: Use the /individual-doc-types endpoint to get specific document types within each group.

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Individual Document Types

Retrieve 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.

Endpoint: GET /api/v1/settings/individual-doc-types

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/individual-doc-types" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "id": 1,
    "description": "RSA ID Book",
    "name": "rsaIDBook",
    "docID": 1,
    "active": true
  },
  {
    "id": 2,
    "description": "RSA ID Card",
    "name": "rsaIDCard",
    "docID": 1,
    "active": true
  },
  {
    "id": 3,
    "description": "Passport",
    "name": "passport",
    "docID": 1,
    "active": true
  },
  {
    "id": 10,
    "description": "Utility Bill",
    "name": "utilityBill",
    "docID": 2,
    "active": true
  }
]

Response Fields:

• id (number): Unique identifier for the document type (use as IndividualDocTypesID when uploading documents)
• description (string): Human-readable description of the document type (e.g., "RSA ID Book")
• name (string): Technical identifier for form fields (e.g., "rsaIDBook")
• docID (number): Parent document group ID - links to /individual-docs endpoint. Use this to group document types by their parent category.
• active (boolean): Whether the document type is active and available for selection

Use Cases:

• Display specific document options in dropdowns (e.g., "RSA ID Book", "Passport")
• Filter document types by document group using the docID field
• Build dynamic forms that show relevant document types based on selected group

Usage: When uploading documents, you need both individualDocsID (from /individual-docs) and IndividualDocTypesID (this id field) to specify which document group and type the uploaded file represents.

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Entity Document Groups

Retrieve 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.

Endpoint: GET /api/v1/settings/entity-docs

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/entity-docs" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "entityDocsID": 1,
    "chkbxDocCheckName": "chkbxDocIdentity",
    "docName": "Identity",
    "docRequiredHighRisk": "Copy of ID Document original sighted",
    "docRequiredLowRisk": "Copy of ID Document",
    "docCheckDesc": "ID Number given by Client corresponds to ID number on documentation",
    "selectDocTypeName": "identityDocSelect",
    "highRiskRequired": true,
    "lowRiskRequiredDoc": true,
    "pepRequiredDoc": true,
    "isActive": true,
    "ftrRequiredDoc": false,
    "showUBO": true,
    "showTrustRelatedParty": true,
    "trustRelatedPartyRequired": true,
    "EntityDoc": true,
    "uboIndividualHighRisk": true,
    "uboTrustHighRisk": true,
    "mediumRiskRequiredDoc": true,
    "docRequiredMediumRisk": "Copy of ID Document"
  }
]

Response Fields: Similar to individual documents, but with entityDocsID instead of individualDocsID and EntityDoc instead of IndividualDoc. Also includes UBO and trust-related party flags.

Use Cases:

• Display required document categories for entity onboarding
• Determine document requirements based on risk level and entity type
• Guide clients through entity document collection process
• Support UBO (Ultimate Beneficial Owner) and trust-related party documentation

Next Step: Use the /entity-doc-types endpoint to get specific document types within each group.

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Entity Document Types

Retrieve 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 entityDocsID field to link document types to their parent document group from the /entity-docs endpoint.

Endpoint: GET /api/v1/settings/entity-doc-types

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/entity-doc-types" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "EntityDocTypesID": 1,
    "docTypeDesc": "Certificate of Incorporation",
    "docTypeName": "certificateOfIncorporation",
    "entityDocsID": 1,
    "isActive": true
  },
  {
    "EntityDocTypesID": 2,
    "docTypeDesc": "Memorandum of Association",
    "docTypeName": "memorandumOfAssociation",
    "entityDocsID": 1,
    "isActive": true
  },
  {
    "EntityDocTypesID": 3,
    "docTypeDesc": "Articles of Association",
    "docTypeName": "articlesOfAssociation",
    "entityDocsID": 1,
    "isActive": true
  }
]

Response Fields:

• EntityDocTypesID (number): Unique identifier for the document type (used in entity document uploads)
• docTypeDesc (string): Human-readable description
• docTypeName (string): Internal name/identifier
• entityDocsID (number): ID of the parent document group (from /entity-docs)
• isActive (boolean): Whether the document type is active

Use Cases:

• Display specific document options in dropdowns (e.g., "Certificate of Incorporation", "Memorandum of Association")
• Filter document types by document group using the entityDocsID field
• Build dynamic forms that show relevant document types based on selected group

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Trust Document Groups

Retrieve 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.

Endpoint: GET /api/v1/settings/trust-docs

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/trust-docs" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "trustDocsID": 1,
    "chkbxDocCheckName": null,
    "docName": "Trust Deeds",
    "docRequiredHighRisk": "Certified copy of Trust Deeds and Amendments",
    "docRequiredLowRisk": "Certified copy of Trust Deeds and Amendments",
    "docCheckDesc": "Certified copy of Trust Deeds and Amendments",
    "selectDocTypeName": "trustDeeds",
    "highRiskRequired": true,
    "lowRiskRequiredDoc": true,
    "pepRequiredDoc": null,
    "isActive": true,
    "additionalDocs": false,
    "ftrRequiredDoc": false,
    "showUBO": null,
    "docRequiredMediumRisk": "Certified copy of Trust Deeds and Amendments",
    "mediumRiskRequiredDoc": true
  }
]

Response Fields: Similar structure to individual/entity documents, but with trustDocsID and trust-specific fields. Some fields may be null if not applicable to trusts.

Use Cases:

• Display required document categories for trust onboarding
• Determine document requirements based on risk level
• Guide clients through trust document collection process

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Transaction Settings

Get Transaction Types

Retrieve 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.

Endpoint: GET /api/v1/settings/transaction-types

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/transaction-types" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "id": 1,
    "name": "Cash Deposit",
    "active": true
  },
  {
    "id": 2,
    "name": "Wire Transfer",
    "active": true
  },
  {
    "id": 103,
    "name": "Annual Financial Statements",
    "active": true
  }
]

Response Fields:

• id (number): Unique identifier for the transaction type
• name (string): Description of the transaction type
• active (boolean): Whether the transaction type is active

Use Cases:

• Populate transaction type dropdowns in transaction forms
• Classify transactions for reporting and compliance
• Support transaction monitoring and risk assessment

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Transaction Frequencies

Retrieve 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.

Endpoint: GET /api/v1/settings/transaction-frequencies

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/transaction-frequencies" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "id": 1,
    "description": "Monthly",
    "active": true,
    "additionalQuestions": false
  },
  {
    "id": 2,
    "description": "Quarterly",
    "active": true,
    "additionalQuestions": false
  },
  {
    "id": 3,
    "description": "Annually",
    "active": true,
    "additionalQuestions": false
  },
  {
    "id": 4,
    "description": "One-time",
    "active": true,
    "additionalQuestions": true
  }
]

Response Fields:

• id (number): Unique identifier for the frequency
• description (string): Description of the frequency
• active (boolean): Whether the frequency is active
• additionalQuestions (boolean): Whether additional questions are required

Use Cases:

• Populate frequency dropdowns in transaction forms
• Assess transaction patterns for risk analysis
• Support compliance reporting on transaction patterns

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Transaction Funding Sources

Retrieve 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.

Endpoint: GET /api/v1/settings/transaction-fundings

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/transaction-fundings" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "id": 1,
    "name": "Bank Transfer",
    "active": true,
    "additionalQuestions": true
  },
  {
    "id": 2,
    "name": "Cash",
    "active": true,
    "additionalQuestions": true
  },
  {
    "id": 3,
    "name": "Credit Card",
    "active": true,
    "additionalQuestions": false
  },
  {
    "id": 4,
    "name": "Cheque",
    "active": true,
    "additionalQuestions": true
  }
]

Response Fields:

• id (number): Unique identifier for the funding source
• name (string): Description of the funding source
• active (boolean): Whether the funding source is active
• additionalQuestions (boolean): Whether additional questions are required

Use Cases:

• Populate funding source dropdowns in transaction forms
• Identify source of funds for AML (Anti-Money Laundering) compliance
• Support transaction monitoring and risk assessment

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Compliance & Additional Settings

Get Wealth Sources

Retrieve 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.

Endpoint: GET /api/v1/settings/wealth-sources

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/wealth-sources" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "wealthSourceID": 1,
    "wealthSourceDesc": "Salary",
    "isActive": true,
    "additionalQuestions": false
  },
  {
    "wealthSourceID": 2,
    "wealthSourceDesc": "Business Income",
    "isActive": true,
    "additionalQuestions": true
  },
  {
    "wealthSourceID": 3,
    "wealthSourceDesc": "Inheritance",
    "isActive": true,
    "additionalQuestions": true
  },
  {
    "wealthSourceID": 4,
    "wealthSourceDesc": "Investment Returns",
    "isActive": true,
    "additionalQuestions": true
  }
]

Response Fields:

• wealthSourceID (number): Unique identifier for the wealth source
• wealthSourceDesc (string): Description of the wealth source
• isActive (boolean): Whether the wealth source is active
• additionalQuestions (boolean): Whether additional questions are required

Use Cases:

• Populate wealth source dropdowns in client onboarding forms
• Support Source of Wealth declarations for high-risk clients
• Enable compliance with AML regulations requiring wealth origin documentation

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Public Official Types

Retrieve 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.

Endpoint: GET /api/v1/settings/public-official-types

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/public-official-types" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "PublicOfficialTypeId": 1,
    "PublicOfficialTypeDesc": "Politically Exposed Person",
    "IsActive": true
  },
  {
    "PublicOfficialTypeId": 2,
    "PublicOfficialTypeDesc": "Head of State",
    "IsActive": true
  },
  {
    "PublicOfficialTypeId": 3,
    "PublicOfficialTypeDesc": "Senior Government Official",
    "IsActive": true
  }
]

Response Fields:

• PublicOfficialTypeId (number): Unique identifier for the public official type
• PublicOfficialTypeDesc (string): Description of the type
• IsActive (boolean): Whether the type is active

Use Cases:

• Populate PEP type dropdowns in client onboarding forms
• Identify clients who are Politically Exposed Persons
• Trigger enhanced due diligence workflows for PEP clients
• Support compliance with PEP regulations

Note: Returns partner-specific settings if configured, otherwise returns default system settings.

---

Get Trust Related Party Types

Retrieve 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.

Endpoint: GET /api/v1/settings/trust-related-party-types

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/trust-related-party-types" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "trustRelatedPartyTypeID": 1,
    "trustRelatedPartyTypeDesc": "Beneficiary",
    "isActive": true
  },
  {
    "trustRelatedPartyTypeID": 2,
    "trustRelatedPartyTypeDesc": "Trustee",
    "isActive": true
  },
  {
    "trustRelatedPartyTypeID": 3,
    "trustRelatedPartyTypeDesc": "Settlor",
    "isActive": true
  },
  {
    "trustRelatedPartyTypeID": 4,
    "trustRelatedPartyTypeDesc": "Protector",
    "isActive": true
  }
]

Response Fields:

• trustRelatedPartyTypeID (number): Unique identifier for the type
• trustRelatedPartyTypeDesc (string): Description of the type
• isActive (boolean): Whether the type is active

Use Cases:

• Populate trust party type dropdowns in trust onboarding forms
• Categorize parties associated with trust entities
• Support trust compliance and documentation requirements

---

Get Trust Masters Courts

Retrieve a list of Masters of the High Court offices where trusts can be registered. In South Africa, trusts must be registered with a Master's Office, and this endpoint provides the available registration offices (e.g., "Cape Town Masters Office", "Johannesburg Masters Office"). This information is required during trust onboarding for compliance purposes.

Endpoint: GET /api/v1/settings/trust-masters-courts

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/trust-masters-courts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "trustMastersCourtID": 1,
    "trustMastersCourtName": "Bisho Masters Office",
    "isActive": true
  },
  {
    "trustMastersCourtID": 2,
    "trustMastersCourtName": "Cape Town Masters Office",
    "isActive": true
  },
  {
    "trustMastersCourtID": 3,
    "trustMastersCourtName": "Johannesburg Masters Office",
    "isActive": true
  },
  {
    "trustMastersCourtID": 4,
    "trustMastersCourtName": "Durban Masters Office",
    "isActive": true
  }
]

Response Fields:

• trustMastersCourtID (number): Unique identifier for the court
• trustMastersCourtName (string): Name of the Masters Office
• isActive (boolean): Whether the court is active

Use Cases:

• Populate Master's Court dropdowns in trust registration forms
• Identify the registration office for trust compliance
• Support trust onboarding and compliance workflows

---

Get Custom Questions

Retrieve 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. If no custom questions are configured or enabled, the customQuestions array will be empty.

Endpoint: GET /api/v1/settings/custom-questions

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/custom-questions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

{
  "customQuestions": [
    {
      "id": 1,
      "question": "What is your preferred communication method?",
      "type": "select",
      "required": false,
      "options": ["Email", "SMS", "Phone"],
      "enabled": true
    },
    {
      "id": 2,
      "question": "How did you hear about us?",
      "type": "text",
      "required": false,
      "enabled": true
    }
  ]
}

Response Fields:

• customQuestions (array): Array of custom questions (empty if none configured)
  • id (number): Unique identifier for the question
  • question (string): The question text to display
  • type (string): Type of question (e.g., "text", "select", "checkbox", "textarea")
  • required (boolean): Whether the question is required
  • options (array, optional): Array of options for select/checkbox types
  • enabled (boolean): Whether the question is enabled

Note: If no custom questions are configured or enabled, customQuestions will be an empty array.

Use Cases:

• Display partner-specific questions in client onboarding forms
• Collect additional client information for partner business needs
• Support white-labeling and partner customization

Usage: Display these questions in your client onboarding forms and include the responses in the customQuestions field when creating individuals.

---

Get Partner Users

Retrieve 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.

Endpoint: GET /api/v1/settings/users

Request Example:

curl -X GET "https://sandboxapi.efica.co.za/api/v1/settings/users" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Example:

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "role": "Admin",
    "email": "admin@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "active": true
  },
  {
    "id": "223e4567-e89b-12d3-a456-426614174001",
    "role": "User",
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "active": true
  }
]

Response Fields:

• id (string): User UUID (unique identifier) - use this as userID or userUUID in other API calls
• role (string): User role (e.g., "Admin", "User")
• email (string): User email address
• firstName (string): User's first name
• lastName (string): User's last name
• active (boolean): Whether the user account is active

Note: Only returns users who have accepted terms and conditions and confirmed their email.

Use Cases:

• Display partner team members in user management interfaces
• Show user roles and permissions
• Support user administration workflows
• Assign individuals to specific users

Usage: Use the id field when you need to specify a user in API calls (e.g., userID in create individual, userUUID in confirm documents).

---

Error Handling

All endpoints return standard error responses for common scenarios. Every endpoint includes documentation for the following error responses:

Standard Error Responses

Status Code	Description	Common Causes
200	Success	Request completed successfully
400	Bad Request	Invalid query parameters or malformed request body
401	Unauthorized	Missing or invalid OAuth2 token, or token expired
500	Internal Server Error	Unexpected server error occurred

Error Response Format

All error responses follow this format:

{
  "statusCode": 401,
  "message": "Unauthorized - Invalid or missing OAuth2 token"
}

Common Error Scenarios

1. Missing or Invalid Token

401 Unauthorized:

{
  "statusCode": 401,
  "message": "Unauthorized - Invalid or missing OAuth2 token"
}

Solution:

• Ensure you include the Authorization: Bearer YOUR_ACCESS_TOKEN header
• Verify your access token hasn't expired (tokens expire after 1 hour)
• Use the refresh token to get a new access token if expired
• Check that the token is correctly formatted (no extra spaces or characters)

2. Invalid Query Parameters

400 Bad Request:

{
  "statusCode": 400,
  "message": "Bad Request - Invalid query parameters",
  "error": "Validation failed"
}

Solution:

• Check that query parameters match the expected format
• For boolean parameters like isActive, use true or false (not 1 or 0)
• Verify parameter names are spelled correctly
• Check that required parameters are provided

3. Internal Server Error

500 Internal Server Error:

{
  "statusCode": 500,
  "message": "Internal Server Error",
  "error": "An unexpected error occurred"
}

Solution:

• Retry the request after a short delay
• If the error persists, contact support with the request details
• Check the API status page for known issues
• Implement retry logic with exponential backoff

4. Partner Access Issues

All responses are automatically filtered by partner. If you don't see expected data:

• Verify you're using the correct partner account token
• Check that the settings are configured for your partner
• Some settings may be partner-specific and not available to all partners
• Contact your account manager if you believe settings should be available

---

Best Practices

1. Error Handling

• Always handle 401 errors: Implement token refresh logic to automatically obtain new tokens
• Retry logic: Implement retry with exponential backoff for transient errors (500, network issues)
• Log errors: Log errors for debugging and monitoring
• Graceful degradation: If settings fail to load, use default values or cached data
• User-friendly messages: Display user-friendly error messages instead of raw API errors

2. Performance

• Fetch on startup: Consider fetching settings data on application startup or periodically
• Batch requests: If possible, fetch multiple settings in parallel using Promise.all()
• Lazy loading: Load settings only when needed (e.g., load document types when user selects a document group)
• Don't fetch on every request: Settings are read-only and don't change frequently

3. Partner-Specific Data

• Automatic filtering: All responses are automatically filtered by your partner - you don't need to filter manually
• Partner isolation: You can only access settings for your own partner account
• Custom questions: Custom questions are partner-specific - if not configured, the array will be empty
• Partner customization: Be aware that some settings may be customized per partner

4. Document Management

• Document groups and types: Always fetch both document groups and document types
• Check requirements: Use the risk-level flags (highRiskRequired, lowRiskRequiredDoc, mediumRiskRequiredDoc) to determine which documents are required
• Validate before upload: Check document requirements before allowing users to upload

5. Integration Patterns

• Dropdown population: Use settings endpoints to populate dropdown lists and form fields
• Validation: Use settings data to validate user input (e.g., ensure selected country exists and is active)
• Dynamic forms: Use additionalQuestions flags to show/hide additional form fields
• Document workflow: Use document settings to guide users through required document uploads
• Risk assessment: Use risk level requirements to determine which documents to request from clients

---

Quick Reference

Endpoint Summary

Category	Endpoint	Method	Description
Geographic	/countries	GET	Get countries list (supports isActive filter)
Employment	/employment-industries	GET	Get employment industries
Employment	/employment-types	GET	Get employment types
Entity	/entity-industries	GET	Get entity industries
Entity	/entity-types	GET	Get entity types
Documents	/individual-docs	GET	Get individual document groups
Documents	/individual-doc-types	GET	Get individual document types
Documents	/entity-docs	GET	Get entity document groups
Documents	/entity-doc-types	GET	Get entity document types
Documents	/trust-docs	GET	Get trust document groups
Transactions	/transaction-types	GET	Get transaction types
Transactions	/transaction-frequencies	GET	Get transaction frequencies
Transactions	/transaction-fundings	GET	Get funding sources
Compliance	/wealth-sources	GET	Get wealth sources
Compliance	/public-official-types	GET	Get public official types (PEP)
Trust	/trust-related-party-types	GET	Get trust related party types
Trust	/trust-masters-courts	GET	Get trust masters courts
Partner	/custom-questions	GET	Get custom questions (partner-specific)
Partner	/users	GET	Get partner users

Authentication Header

Authorization: Bearer YOUR_ACCESS_TOKEN

Base URLs

• Sandbox: https://sandboxapi.efica.co.za/api/v1/settings
• Production: https://loginapi.efica.co.za/api/v1/settings

Standard Error Responses

All endpoints return:

• 400: Bad Request - Invalid parameters
• 401: Unauthorized - Invalid or missing token
• 500: Internal Server Error - Server error

---

Complete Integration Example

Here's a complete example of fetching and using settings in JavaScript:

// Configuration
const API_BASE_URL = 'https://sandboxapi.efica.co.za/api/v1/settings';
let ACCESS_TOKEN = 'your-access-token-here';

// Helper function to make authenticated requests
async function fetchSettings(endpoint, queryParams = {}) {
  const queryString = new URLSearchParams(queryParams).toString();
  const url = `${API_BASE_URL}${endpoint}${queryString ? `?${queryString}` : ''}`;
  
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${ACCESS_TOKEN}`,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    if (response.status === 401) {
      // Token expired, refresh it
      ACCESS_TOKEN = await refreshAccessToken();
      // Retry the request
      return fetchSettings(endpoint, queryParams);
    }
    throw new Error(`API Error: ${response.status} ${response.statusText}`);
  }

  return response.json();
}

// Fetch countries (active only)
const countries = await fetchSettings('/countries', { isActive: true });

// Fetch employment industries
const employmentIndustries = await fetchSettings('/employment-industries');

// Fetch individual documents and types in parallel
const [individualDocs, individualDocTypes] = await Promise.all([
  fetchSettings('/individual-docs'),
  fetchSettings('/individual-doc-types')
]);

// Build document selection UI
function buildDocumentSelector(docs, docTypes) {
  // Group document types by document group
  const docTypesByGroup = docTypes.reduce((acc, type) => {
    if (!acc[type.docID]) acc[type.docID] = [];
    acc[type.docID].push(type);
    return acc;
  }, {});

  // Create UI structure
  return docs.map(doc => ({
    group: {
      id: doc.id,
      name: doc.name,
      description: doc.description,
      required: {
        highRisk: doc.highRiskRequired,
        mediumRisk: doc.mediumRiskRequired,
        lowRisk: doc.lowRiskRequired
      }
    },
    types: docTypesByGroup[doc.id] || []
  }));
}

const documentSelector = buildDocumentSelector(individualDocs, individualDocTypes);

// Fetch transaction settings in parallel
const [transactionTypes, frequencies, fundings] = await Promise.all([
  fetchSettings('/transaction-types'),
  fetchSettings('/transaction-frequencies'),
  fetchSettings('/transaction-fundings')
]);

// Fetch custom questions
const customQuestionsData = await fetchSettings('/custom-questions');
const customQuestions = customQuestionsData.customQuestions || [];

// Fetch partner users
const users = await fetchSettings('/users');

// Use settings to populate forms
function populateForm() {
  // Populate country dropdown
  const countrySelect = document.getElementById('country');
  countries.forEach(country => {
    if (country.active) {
      const option = document.createElement('option');
      option.value = country.id;
      option.textContent = country.name;
      if (country.fatf) {
        option.dataset.fatf = 'true';
        option.textContent += ' (FATF)';
      }
      countrySelect.appendChild(option);
    }
  });

  // Populate employment type dropdown
  const employmentTypeSelect = document.getElementById('employmentType');
  employmentIndustries.forEach(industry => {
    if (industry.active) {
      const option = document.createElement('option');
      option.value = industry.id;
      option.textContent = industry.name;
      if (industry.additionalQuestions) {
        option.dataset.requiresQuestions = 'true';
      }
      employmentTypeSelect.appendChild(option);
    }
  });

  // Render custom questions
  const customQuestionsContainer = document.getElementById('customQuestions');
  customQuestions.forEach(question => {
    const questionElement = createQuestionElement(question);
    customQuestionsContainer.appendChild(questionElement);
  });
}

// Handle document upload with correct IDs
async function uploadDocument(individualId, file, docGroupId, docTypeId) {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('documents', JSON.stringify([
    { individualDocsID: docGroupId, IndividualDocTypesID: docTypeId }
  ]));

  const response = await fetch(
    `https://sandboxapi.efica.co.za/api/v1/individual/${individualId}/documents`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${ACCESS_TOKEN}`
      },
      body: formData
    }
  );

  return response.json();
}

// Determine required documents based on risk level
function getRequiredDocuments(docs, riskLevel) {
  return docs.filter(doc => {
    switch(riskLevel) {
      case 'high':
        return doc.highRiskRequired;
      case 'medium':
        return doc.mediumRiskRequired;
      case 'low':
        return doc.lowRiskRequired;
      default:
        return false;
    }
  });
}

---

Support

For additional support or questions about the Settings API:

• Email: melissa@efica.co.za

---

Last Updated: 26 January 2026