Overview

This endpoint uploads a file into Fuga and stores it as a document. Optionally the file can be linked to a client, an animal or a consultation, and it can be routed to the document inbox for manual handling. It is part of the Fuga Backend API and follows the same authentication (OAuth2 / JWT bearer).


POST https://<your Fuga environment>/backend/api/files


Content-Type: multipart/form-data, with the required scope api_files:write. The request has two parts:

  • file — the binary file content.

  • metadata — a JSON object describing the file (the fields below).


Metadata fields

The metadata part is a JSON object. This is what each field means in Fuga:


FieldTypeMeaning in Fuga
namestringThe name the document gets in Fuga — this is what the practice sees in the document list.
typestringThe Fuga document type, which determines how the file is categorised. Must be one of: TDocument (general document), TReportMedicalImaging (medical imaging report), TVisitReport (visit / consultation report), TOther (other). Any other value is rejected with a validation error.
descriptionstring, optionalFree-text description shown together with the document. Defaults to empty.
referenceobject, optionalLinks the document to a Fuga record. See "Linking the file" below.
showInInboxboolean, optionalWhether the document appears in the practice's document inbox for manual triage. Defaults to true. See the note below on how this interacts with automatic archiving.
externalReferencestringYour own unique identifier for the file in the source system. Fuga uses it to prevent duplicates — see "Idempotency" below.
externalTimestampdate-time, optionalThe moment the document was created in your system (ISO date-time). Stored on the document. Defaults to the time of upload if omitted.

Linking the file (reference)

The reference object attaches the document to one Fuga record. You may set at most one of the three targets:

  • client — links to a client.

  • animal — links to an animal / patient.

  • clientInteraction — links to a consultation.


Each target must contain exactly one of:

  • id — the Fuga internal id of the record, or

  • number — the human-visible number (client number, patient number, or consultation number).


Rules:

  • Setting more than one target, or a target with both id and number (or neither), is rejected with a validation error.

  • If the target is valid but the record cannot be found, the upload does not fail: the file is stored without a link and a warning (REFERENCE_NOT_FOUND) is returned in the response so you can detect it.


Note on showInInbox: when a valid reference is provided and the practice has automatic archiving enabled, the document is filed directly onto the linked record and is not placed in the inbox — in that case it will not show in the inbox even if showInInbox was true.


Idempotency

Uploads are de-duplicated on externalReference. If you send a file with an externalReference that already exists (same source system), Fuga does not create a second document — it returns the existing one. Practically this means you can safely retry an upload without creating duplicates.


Response

The response body is a JSON object:

  • id — the id of the document in Fuga.

  • url — a URL to the stored file.

  • warnings — a list of non-fatal warnings, each with a code, the field it relates to, and a human-readable message (for example a reference that could not be resolved).


Status codes: 201 Created when a new document was stored, 200 OK when an existing document was returned (duplicate externalReference). A malformed request (missing file or metadata, invalid type, invalid reference) returns 400.


The exact request and response schemas are always available in the interactive Swagger reference at https://<your Fuga environment>/backend/swagger-ui/index.html.