Files

Files (UploadedFile objects) represent uploaded documents, images, and other attachments in the system. A file’s type is either VOUCHER (the primary file behind a voucher) or ATTACHMENT (a supporting file attached to a document).

There is no standalone /files endpoint for listing, fetching, or deleting files directly. Instead:

To attach a new file to a document, include it in the files array when creating or updating a document (POST/PUT/PATCH /documents), with the raw content base64-encoded in content_base64.
To read a document’s files, request the document with with_relations=files.
A voucher’s primary file is the voucher record itself — see Vouchers for how vouchers enter the system through the document-processing pipeline.

File Object Shape

When adding a new entry to a document’s files array, the following parameters are supported:

Parameter	Type	Required	Description
file_name	string	Yes	Name of the file, including extension
content_base64	string	Yes	Base64-encoded file content. Write-only, never returned in responses
content_type	string	No	MIME type of the file. Guessed from the content if omitted
type	string	No	`VOUCHER` or `ATTACHMENT` (default: `ATTACHMENT`)

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: `VOUCHER` or `ATTACHMENT`
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` or `MANUAL`). Only set on files created through the voucher-processing pipeline
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)
preview_url	URL for a single high-resolution preview image (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)
page_images	For multi-page files, a list of `{page_number, preview_url}` objects with a high-resolution preview per page

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": "ATTACHMENT",
    "file_name": "invoice.pdf",
    "content_type": "application/pdf",
    "channel": "API",
    "processing_track": null,
    "size": 1024576,
    "is_active": true,
    "thumbnail_url": "https://example.com/thumbnails/invoice.jpg",
    "preview_url": "https://example.com/previews/invoice.jpg",
    "download_url": "https://example.com/files/invoice-optimized.pdf",
    "original_url": "https://example.com/files/invoice.pdf",
    "page_images": []
}

Usage Examples

Attach a new file to a document by including it in the files array:

curl -X POST "https://api.snapbooks.com/api/v2/documents" \
  -H "Content-Type: application/json" \
  -d '{
    "client_account_id": 123,
    "document_type": "APINV",
    "document_date": "2024-01-15",
    "files": [
      {
        "file_name": "invoice.pdf",
        "content_type": "application/pdf",
        "content_base64": "JVBERi0xLjQK..."
      }
    ]
  }'

Read a document together with its files:

curl "https://api.snapbooks.com/api/v2/documents/123?with_relations=files"

Notes

Files can have multiple derivative versions (thumbnails, optimized versions, page previews)
All URLs are pre-signed and expire after one hour
The system automatically generates optimized versions, thumbnails, and page previews for supported file types
Files marked as inactive are not deleted but hidden from normal queries
content_base64 is only used when adding a new file; it is never included in responses