Individual Applications

Overview

The Individuals API provides comprehensive functionality for managing FICA (Financial Intelligence Centre Act) individual applications. This includes creating new applications, managing existing ones, uploading and verifying documents, and making onboarding decisions. The API follows a structured 4-step process to ensure compliance with FICA regulations.

Authentication

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

Authorization: Bearer <your-jwt-token>

FICA Process Overview

The Individuals API follows a structured 4-step process:

1. Step 1: Create/Update individual basic information
2. Step 2: Verification and risk assessment
3. Step 3: Document management and verification
4. Step 4: Onboarding decision and final report

Core Endpoints

Get Individuals

Retrieve all individual users for the current company with optional filtering and pagination.

URL: GET /individuals
Authentication: Required
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description	Example
take	number	No	Number of records to return (default: 10)	20
skip	number	No	Number of records to skip for pagination	0
orderBy	string	No	Sort order - asc or desc	"desc"
orderByField	string	No	Field to sort by (default: ficaIndividualID)	"dateAdded"
clientReference	string	No	Filter by client reference	"REF123"
firstName	string	No	Filter by first name	"John"
lastName	string	No	Filter by last name	"Doe"
identificationNumber	string	No	Filter by ID number	"1234567890123"
riskDescription	string	No	Filter by risk level	"Low Risk"
ficaStatus	string	No	Filter by FICA status	"Approved"

Example Request

curl -X GET "https://sandboxapi.efica.co.za/individuals?take=20&skip=0&orderBy=desc&orderByField=dateAdded" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "count": 150,
  "individuals": [
    {
      "ficaIndividualID": 123,
      "ficaIndividualGUID": "c12f9d3d-0000-0000-0000-9337099a4fd2",
      "firstName": "John",
      "lastName": "Doe",
      "clientEmail": "john.doe@example.com",
      "identificationNumber": "1234567890123",
      "clientRiskScore": 25,
      "clientApproval": true,
      "clientFaceToFace": true,
      "clientSACitizen": true,
      "clientReference": "REF123",
      "riskDescription": "Low Risk",
      "ficaStatus": "Pending",
      "dateAdded": "2023-12-01T10:30:00.000Z",
      "step1Complete": true,
      "step2Complete": true,
      "step3Complete": false,
      "step4Complete": false,
      "isClone": false,
      "clones": []
    }
  ]
}

Get Individual by ID

Retrieve individual user data by ID.

URL: GET /individuals/{id}
Authentication: Required
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description	Example
id	number	Yes	Individual ID	123

Example Request

curl -X GET "https://sandboxapi.efica.co.za/individuals/123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Create Individual

Create a new entry in the FICA individual database.

URL: POST /individuals
Authentication: Required
Content-Type: application/json

Request Body

{
  "clientReference": "REF123",
  "firstName": "John",
  "lastName": "Doe",
  "clientFaceToFace": true,
  "clientSACitizen": true,
  "identificationNumber": "1234567890123",
  "passportNumber": "",
  "clientCitizenshipCountry": 118,
  "clientCountryResidence": 118,
  "sarsNumber": "",
  "clientEmail": "john.doe@example.com",
  "clientPhone": "0123456789",
  "residentialLine1": "123 Main Street",
  "residentialLine2": "",
  "residentialLine3": "",
  "residentialZIPCode": "2000",
  "residentialCountry": 118,
  "employmentStatus": 1,
  "clientOccupation": "Software Developer",
  "employerName": "Tech Corp",
  "employmentIndustry": 1,
  "employerIndustry": "Technology",
  "linkedForexTransactionQuestion": false,
  "transactionType": 1,
  "transactionFrequency": 1,
  "sourceFunding": 1,
  "sourceFundingOther": "",
  "sourceWealth": 1,
  "sourceWealthOther": "",
  "clientApproval": true
}

Example Request

curl -X POST "https://sandboxapi.efica.co.za/individuals" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientReference": "REF123",
    "firstName": "John",
    "lastName": "Doe",
    "clientFaceToFace": true,
    "clientSACitizen": true,
    "identificationNumber": "1234567890123",
    "clientEmail": "john.doe@example.com",
    "clientPhone": "0123456789",
    "residentialLine1": "123 Main Street",
    "residentialZIPCode": "2000",
    "residentialCountry": 118,
    "employmentStatus": 1,
    "clientOccupation": "Software Developer",
    "employerName": "Tech Corp",
    "transactionType": 1,
    "transactionFrequency": 1,
    "sourceFunding": 1,
    "sourceWealth": 1,
    "clientApproval": true
  }'

Update Individual

Update FICA individual step 1 data.

URL: PUT /individuals/{id}
Authentication: Required
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description	Example
id	number	Yes	Individual ID	123

Request Body

Same structure as Create Individual request.

Document Management

Get Documents

Retrieve all documents uploaded for the individual.

URL: GET /individuals/{id}/documents
Authentication: Required
Content-Type: application/json

Example Request

curl -X GET "https://sandboxapi.efica.co.za/individuals/123/documents" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "requiredDocuments": [
    {
      "id": 1,
      "name": "ID Document",
      "description": "South African ID document or passport",
      "required": true,
      "uploaded": true,
      "docTypeID": 1,
      "docSubTypeID": 1
    },
    {
      "id": 2,
      "name": "Proof of Address",
      "description": "Utility bill or bank statement",
      "required": true,
      "uploaded": false,
      "docTypeID": 2,
      "docSubTypeID": 1
    }
  ],
  "submittedDocuments": [
    {
      "id": 1,
      "name": "ID Document",
      "url": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpeg",
      "uploadDate": "2023-12-01T10:30:00.000Z",
      "docTypeID": 1,
      "docSubTypeID": 1,
      "fileSize": 1024000,
      "isActive": true
    }
  ]
}

Upload Document

Upload a document for the specified individual and document type.

URL: POST /individuals/{id}/{individualDocsID}/{IndividualDocTypesID}/document
Authentication: Required
Content-Type: multipart/form-data

Path Parameters

Parameter	Type	Required	Description	Example
id	number	Yes	Individual ID	123
individualDocsID	number	Yes	Document type ID	1
IndividualDocTypesID	number	Yes	Document subtype ID	1

Form Data

Field	Type	Required	Description
file	file	Yes	Document file to upload

Example Request

curl -X POST "https://sandboxapi.efica.co.za/individuals/123/1/1/document" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@/path/to/document.pdf"

Success Response (200 OK)

{
  "result": {
    "etag": "\"0x8DDDAA3EB83C4BE\"",
    "lastModified": "2023-12-01T10:30:00.000Z",
    "contentMD5": {
      "type": "Buffer",
      "data": [156, 82, 241, 70, 139, 208, 99, 165, 179, 236, 97, 103, 40, 128, 177, 88]
    },
    "clientRequestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "requestId": "4258ed92-801e-000a-6d8c-0cd7fb000000",
    "version": "2023-12-01",
    "date": "2023-12-01T10:30:00.000Z",
    "isServerEncrypted": true
  },
  "docURL": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpeg",
  "ficaIndividualDocsID": 12345
}

Delete Document

Delete an existing document for the individual.

URL: DELETE /individuals/{ficaIndividualDocsID}/document
Authentication: Required
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description	Example
ficaIndividualDocsID	number	Yes	Individual document ID	12345

Example Request

curl -X DELETE "https://sandboxapi.efica.co.za/individuals/12345/document" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Verify Documents

Verify that all required documents have been uploaded.

URL: POST /individuals/{id}/verify-documents
Authentication: Required
Content-Type: application/json

Request Body

{
  "docsUploadedReviewed": true
}

Verification and Risk Assessment

Complete Step 2 Verification

Save step 2 verification details and calculate individual risk score.

URL: POST /individuals/{id}/verify-results
Authentication: Required
Content-Type: application/json

Request Body

{
  "clientForeignOfficial": false,
  "clientForeignOfficialType": 0,
  "adverseSearchKYC": false
}

Example Request

curl -X POST "https://sandboxapi.efica.co.za/individuals/123/verify-results" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientForeignOfficial": false,
    "clientForeignOfficialType": 0,
    "adverseSearchKYC": false
  }'

Get Verification Results

Retrieve user details and results from SA ID number search.

URL: GET /individuals/{id}/verify-results
Authentication: Required
Content-Type: application/json

Onboarding Decision

Make Onboarding Decision

Make an onboarding decision for the FICA individual application (Step 4).

URL: POST /individuals/{id}/onboard-decision
Authentication: Required
Content-Type: application/json

Request Body

{
  "additionalSuspicions": false,
  "additionalSuspicionsReason": "",
  "sendToCharter": false,
  "sendToCharterComments": "",
  "referredClientOnboardingDecision": "",
  "referredTransactionApproveOnboardingReason": "",
  "referredTransactionApproveAdditionalComments": "",
  "referredTransactionDeclineOnboardingReason": "",
  "referredTransactionReferOnboardingReason": "",
  "nextFicaReviewDate": "2024-12-31T00:00:00.000Z",
  "clientOnboardingDecision": "Approved",
  "referredToAdminID": null,
  "referredToAdminReason": "",
  "transactionApproveOnboardingReason": "",
  "transactionApproveAdditionalComments": "",
  "transactionDeclineOnboardingReason": ""
}

Additional Features

Get Individuals Referred to Admin

Retrieve all individual users flagged with a review status by an administrator.

URL: GET /individuals/referred-to-admin
Authentication: Required (Admin only)
Content-Type: application/json

Get Individuals for Ongoing Monitoring

Retrieve all users to manage ongoing monitoring.

URL: GET /individuals/ongoing-monitoring
Authentication: Required
Content-Type: application/json

Clone User

Clone an existing FICA individual application to start a new FICA search.

URL: POST /individuals/clone
Authentication: Required
Content-Type: application/json

Request Body

{
  "clonedParentID": 123
}

Clone for Charter

Clone individual details for Charter without affecting the original application.

URL: POST /individuals/clone-charter
Authentication: Required
Content-Type: application/json

Request Body

{
  "id": 123,
  "accountType": "Investment",
  "adminFeeType": "Standard",
  "adminFeeClient": 100,
  "investmentAmount": 10000
}

Workflow Diagrams

Create Individual Workflow

Edit Individual Workflow

Error Handling

HTTP Status Codes

Status Code	Description	Common Causes
200	Success	Request completed successfully
400	Bad Request	Invalid input data or missing required fields
401	Unauthorized	Invalid or missing authentication token
403	Forbidden	Insufficient permissions for the requested operation
404	Not Found	Individual or resource not found
413	Payload Too Large	File upload exceeds size limit
415	Unsupported Media Type	Invalid file format for upload
500	Internal Server Error	Server-side error

Error Response Format

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "identificationNumber",
      "message": "Identification number is required"
    }
  ]
}

Best Practices

1. Authentication

• Always include valid Bearer tokens in requests
• Implement token refresh logic for long-running applications
• Store tokens securely and never expose them in client-side code

2. Error Handling

• Implement proper error handling for all API calls
• Use appropriate HTTP status codes for different error types
• Provide meaningful error messages to users

3. File Uploads

• Ensure files meet size and format requirements (max 40MB, PDF/PNG/JPEG)
• Validate file types before upload
• Implement retry logic for failed uploads

4. Workflow Compliance

• Follow the 4-step FICA process in order
• Don't skip steps or call endpoints out of sequence
• Validate step completion before proceeding

5. Data Validation

• Validate all input data before submission
• Use appropriate data types and formats
• Handle optional fields appropriately

File Upload Guidelines

Supported Formats

• PDF: .pdf
• Images: .png, .jpeg, .jpg

Size Limits

• Maximum file size: 40MB per file
• Recommended size: Under 5MB for optimal performance

Upload Process

1. Verify file format and size before upload
2. Use appropriate document type and subtype IDs
3. Handle upload progress and errors
4. Verify upload success before proceeding

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify your JWT token is valid and not expired
   • Check that the token is included in the Authorization header
   • Ensure you have the correct permissions

2. Validation Errors

   • Check all required fields are provided
   • Verify data types and formats
   • Ensure field values meet validation rules

3. File Upload Issues

   • Verify file size is under 40MB
   • Check file format is supported
   • Ensure correct document type and subtype IDs

4. Workflow Errors

   • Follow the 4-step process in order
   • Complete each step before proceeding to the next
   • Verify step completion status

Support

For technical support or questions about the Individuals API:

1. Check the API documentation for endpoint details and examples
2. Review error messages for specific issue details
3. Contact support at melissa@efica.co.za
4. Include relevant information:
   • API endpoint being called
   • Request data (without sensitive information)
   • Error response details
   • Steps to reproduce the issue

---

Last Updated: 14 August 2025