API Reference

Files

Secure, time-limited file uploads and downloads with external storage integration.

Facilioo does not store file contents directly within its API or database. Instead, it provides pre-signed, time-limited URLs for uploading and downloading files. These URLs enable secure and efficient direct interaction with the underlying file storage (typically AWS S3) without routing file data through the facilioo backend.

File Types

Files are classified by type, which is part of the system’s API and managed as relatively static data. Examples include PDF documents, images, and other formats. File types can be fetched via the API to ensure correct categorization when creating or updating file metadata.

Flows

There are different flow possible in terms of files. Essentially, they behave all very similar, as the API builds the bridge between the client and the actual file storage. Furthermore, it maintains a metadata shell to link files to documents, process feeds, etc.

Uploading Files

The file upload process consists of several steps:

  1. Obtain File Type ID:
    Retrieve the file types available in the system via API to identify the appropriate type for your file (e.g., PDF → id = 1).
  2. Create File Metadata:
    Create a new File entity in facilioo via the API, including details such as the original file name, file type, and optional external identifiers.
  3. Request Upload URL:
    Call the endpoint PUT /api/files/{id}/upload to obtain a pre-signed, time-limited upload URL. This URL is not an API endpoint but a direct, authorized link to the external file storage.
  4. Upload File:
    Use the obtained upload URL to upload your file via an HTTP PUT request directly to the storage service.

📘

Note

To ensure uniqueness and privacy, filenames are hashed before storing in the external file storage system.

Downloading Files

For file retrieval, facilioo provides time-sensitive download URLs:

  • You can request a download URL via the API, which grants temporary, secure access to the file in external storage.
  • This mechanism ensures efficient delivery without the file passing through the API servers.
  • Download URLs expire after a short period to maintain security.

Thumbnails and Image Support

  • For image file types, facilioo automatically generates thumbnails.
  • Thumbnail URLs are similarly time-limited and can be retrieved through the API.
  • These thumbnails enable quick previews in the UI without requiring full file downloads.

Security and Authorization

  • All upload and download URLs are time-sensitive and unique per request to prevent unauthorized access.
  • Files are always associated with metadata entities linking them to parties, units, contracts, or other domain objects.
  • Access to file URLs respects the system’s access control and sharing settings.