File Management

Overview

The File API provides functionality for uploading, downloading, streaming, and managing documents within the eFICA system. This includes file uploads for FICA applications, document streaming for viewing, and document linking capabilities.

Base URL

https://sandboxapi.efica.co.za/file

Authentication

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

Authorization: Bearer <your-jwt-token>

Core Endpoints

Upload File

Upload a file to the system. This endpoint is private and only available in the private API documentation.

URL: POST /file/uploadFile
Authentication: Required
Content-Type: multipart/form-data

Form Data

Field	Type	Required	Description
file	file	Yes	File to upload

Example Request

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

Success Response (200 OK)

{
  "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
}

Get File Stream

Stream a file for viewing in the browser.

URL: GET /file/stream/{filename}
Authentication: Required
Content-Type: application/octet-stream

Path Parameters

Parameter	Type	Required	Description	Example
filename	string	Yes	Name of the file to stream	document.pdf

Example Request

curl -X GET "https://sandboxapi.efica.co.za/file/stream/document.pdf" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Success Response (200 OK)

Returns the file content with appropriate Content-Type header based on file extension.

Get File Download

Download a file with proper Content-Disposition header.

URL: GET /file/download/{filename}
Authentication: Required
Content-Type: application/octet-stream

Path Parameters

Parameter	Type	Required	Description	Example
filename	string	Yes	Name of the file to download	document.pdf

Example Request

curl -X GET "https://sandboxapi.efica.co.za/file/download/document.pdf" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  --output downloaded_file.pdf

Success Response (200 OK)

Returns the file content with Content-Disposition: attachment header.

Add Document Link

Link a document to a FICA application.

URL: POST /file/addDocumentLink
Authentication: Required
Content-Type: application/json

Request Body

{
  "docsID": 123,
  "docTypesID": 1,
  "docURL": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.pdf",
  "ficaApplicationID": 456,
  "ficaApplicationType": "individual"
}

Request Body Parameters

Parameter	Type	Required	Description	Example
docsID	number	Yes	Document ID	123
docTypesID	number	Yes	Document type ID	1
docURL	string	Yes	Document URL/filename	"document.pdf"
ficaApplicationID	number	Yes	FICA application ID	456
ficaApplicationType	string	Yes	Application type (individual/entity/trust)	"individual"

Example Request

curl -X POST "https://sandboxapi.efica.co.za/file/addDocumentLink" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "docsID": 123,
    "docTypesID": 1,
    "docURL": "document.pdf",
    "ficaApplicationID": 456,
    "ficaApplicationType": "individual"
  }'

Success Response (200 OK)

{
  "success": true,
  "message": "Document linked successfully",
  "documentLinkID": 789
}

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	File 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": "file",
      "message": "File is required"
    }
  ]
}

Best Practices

1. File Uploads

• Ensure files meet size and format requirements
• Validate file types before upload
• Implement retry logic for failed uploads
• Use appropriate content types

2. Security

• Validate file contents, not just extensions
• Implement virus scanning for uploaded files
• Control access to sensitive documents

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. Validate file contents for security
3. Handle upload progress and errors
4. Verify upload success before proceeding

Troubleshooting

Common Issues

1. Upload Failures

   • Verify file size is under 40MB
   • Check file format is supported
   • Ensure proper authentication
   • Check network connectivity

2. File Not Found

   • Verify filename is correct
   • Ensure proper permissions
   • Validate file path

3. Streaming Issues

   • Check file format compatibility
   • Verify content type headers
   • Ensure proper authentication
   • Check browser compatibility

4. Download Problems

   • Verify file exists
   • Check storage permissions
   • Ensure proper authentication
   • Validate output path

Support

For technical support or questions about the File 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
   • File details (size, format)
   • Error response details
   • Steps to reproduce the issue

---

Last Updated: 14 August 2025