Files
Files represent uploaded documents, images, and other attachments in the system. They can be associated with various entities such as commercial documents, journal entries, and other business objects.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /files | List files |
| POST | /files | Upload a file |
| GET | /files/{id} | Get a specific file |
| DELETE | /files/{id} | Delete a file |
| GET | /files/{id}/download | Download a file |
Upload Parameters
When uploading files via POST /files, the following parameters are supported:
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | The client account ID |
| file | file | Yes | The file to upload |
| processing_track | string | No | Processing workflow mode (DEFAULT, MANUAL, FASTTRACK) |
Processing Tracks
The processing_track parameter controls how uploaded documents are processed:
- DEFAULT (default): Standard AI workflow using all available models (finetuned and general)
- MANUAL: Only generates thumbnails and extracts text via OCR, completely skips AI processing
- FASTTRACK: Full AI workflow but uses only finetuned models for faster, more accurate processing
If not specified, files default to DEFAULT processing track.
Query Parameters
The GET /files endpoint supports the following query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | Filter by client account ID |
| type | string | No | Filter by file type |
| is_active | boolean | No | Filter by active status |
| page | integer | No | Page number for pagination (default: 1) |
| per_page | integer | No | Number of items per page (default: 100) |
File Attributes
| Attribute | Type | Description |
|---|---|---|
| id | integer | The unique identifier of the file |
| created_at | date | When the file was created |
| created_by_id | integer | The ID of the user who created the file |
| updated_at | date | When the file was last updated |
| updated_by_id | integer | The ID of the user who last updated the file |
| client_account_id | integer | The ID of the client account |
| type | string | Type of file (e.g., “FILE”, “VOUCHER”) |
| file_name | string | Original name of the file |
| content_type | string | MIME type of the file |
| channel | string | Upload channel identifier |
| processing_track | string | Processing workflow mode (DEFAULT, MANUAL, FASTTRACK) |
| file_size | integer | Size of the file in bytes |
| is_active | boolean | Whether the file is active |
File URLs
Files can have multiple versions with different URLs:
| URL Type | Description |
|---|---|
| thumbnail_url | URL for a small thumbnail preview (expires in 1 hour) |
| download_url | URL to download the optimized version (expires in 1 hour) |
| original_url | URL for the original uploaded file (expires in 1 hour) |
Relationships
| Relationship | Type | Description |
|---|---|---|
| source_file | UploadedFile | The original file this was derived from |
| target_files | [UploadedFile] | Files derived from this file |
Example Response
{
"id": 1,
"created_at": "2023-05-10T12:00:00Z",
"created_by_id": 123,
"updated_at": "2023-05-10T12:00:00Z",
"updated_by_id": 123,
"client_account_id": 1,
"type": "VOUCHER",
"file_name": "invoice.pdf",
"content_type": "application/pdf",
"channel": "web_upload",
"processing_track": "DEFAULT",
"file_size": 1024576,
"is_active": true,
"thumbnail_url": "https://example.com/thumbnails/invoice.jpg",
"download_url": "https://example.com/files/invoice-optimized.pdf",
"original_url": "https://example.com/files/invoice.pdf"
}
Usage Examples
Upload a file with default processing (full AI workflow):
curl -X POST "https://api.snapbooks.com/files/" \
-F "client_account_id=123" \
-F "file=@invoice.pdf"
Upload a file with manual processing (thumbnail + OCR only):
curl -X POST "https://api.snapbooks.com/files/" \
-F "client_account_id=123" \
-F "processing_track=MANUAL" \
-F "file=@document.pdf"
Upload a file with fast track processing (finetuned models only):
curl -X POST "https://api.snapbooks.com/files/" \
-F "client_account_id=123" \
-F "processing_track=FASTTRACK" \
-F "file=@receipt.pdf"
Notes
- Files can be associated with documents either directly or as attachments
- Files can have multiple derivative versions (thumbnails, optimized versions)
- All URLs are pre-signed and expire after one hour
- The system automatically generates optimized versions and thumbnails for supported file types
- Files marked as inactive are not deleted but hidden from normal queries
- When uploading a file, you can include base64-encoded content using the content_base64 field (only during upload)