intermediate20 minutes
Documents API
Current authenticated routes for managing company compliance documents
Overview
The Documents API manages the authenticated user's company document vault. These are application routes under
/api/v1/documents; they require the logged-in JWT from the web app and a company profile on the user account.Company-scoped access
Regular users can only access documents for their own company. Admin users can access company resources according to server-side authorization checks.
Authentication
Use the httpOnly auth cookie from login or send the current JWT in
Authorization: Bearer <token>. See Authentication for the current auth behavior.Authenticated request
bash
Document Types
The current document type enum supports:
| Type | Expiry required |
|------|-----------------|
|
|
|
|
|
|
|
|
|
|
|
| Type | Expiry required |
|------|-----------------|
|
TAX_CLEARANCE | Yes ||
BBBEE_CERTIFICATE | Yes ||
INSURANCE_CERTIFICATE | Yes ||
SAFETY_CERTIFICATE | Yes ||
CIPC_REGISTRATION | No ||
COMPANY_PROFILE | No ||
FINANCIAL_STATEMENTS | No ||
TAX_COMPLIANCE | No ||
WORKMANS_COMPENSATION | No ||
SHAREHOLDER_REGISTER | No ||
DIRECTORS_REGISTER | No |List Documents
GET /api/v1/documents returns documents for the authenticated user's company plus summary stats.| Parameter | Type | Description |
|-----------|------|-------------|
|
type | string | Filter by document type enum value ||
status | string | valid, expiring, or expired ||
verified | boolean | true or false |List response shape
json
Upload Document
POST /api/v1/documents accepts multipart/form-data.| Field | Type | Required | Description |
|-------|------|----------|-------------|
|
file | File | Yes | PDF, DOC, DOCX, JPG, JPEG, or PNG file ||
documentType | string | Yes | Current document type enum value ||
expiryDate | string | Required for expiry-tracked types | ISO date string ||
description | string | No | Accepted by the route but not currently returned in the document response |Maximum file size is 10MB.
Upload document
bash
Download Vault Document
GET /api/v1/documents/{documentId} streams the authenticated company document file inline when the user has access. The route returns 404 if the database record or stored file cannot be found.Update Document
PUT /api/v1/documents/{documentId} updates document metadata. Regular users can update expiryDate. Only admin users can set verified to true.Update expiry date
bash
Delete Document
DELETE /api/v1/documents/{documentId} removes a document. If the document is referenced by active applications, the route returns 409 with the referencing applications. Add ?force=true to remove references before deleting.Document Stats
GET /api/v1/documents/stats returns company document usage statistics, including the percentage of uploaded documents referenced by applications.Error Handling
| Status | Meaning |
|--------|---------|
| 400 | Invalid request, document type, status, verified value, file type, file size, or expiry date |
| 401 | Missing or invalid JWT |
| 403 | Company profile required, access denied, or non-admin attempted admin-only verification |
| 404 | Document record or stored file was not found |
| 409 | Delete blocked because the document is referenced in active applications |
| 500 | Unexpected server error |
| 503 | Storage or database configuration problem |
| 507 | Insufficient storage space during upload |
|--------|---------|
| 400 | Invalid request, document type, status, verified value, file type, file size, or expiry date |
| 401 | Missing or invalid JWT |
| 403 | Company profile required, access denied, or non-admin attempted admin-only verification |
| 404 | Document record or stored file was not found |
| 409 | Delete blocked because the document is referenced in active applications |
| 500 | Unexpected server error |
| 503 | Storage or database configuration problem |
| 507 | Insufficient storage space during upload |
For the user-facing workflow around this API, see Document Management.