intermediate20 minutes
Documents API
Signed-in application routes for managing company documents; separate from Developer API v2
Overview
These application routes manage the signed-in user's company document vault under
/api/v1/documents. They use the browser session and company context. They are separate from the API-key-authenticated Developer API v2.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 secure HTTP-only session cookie created by the Tenders-SA login flow. Browser requests send
credentials: 'include'; client code must not read tokens from local storage or construct a session Authorization header.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.