Add Document Attachments
Attach one or more files to a document the company issued (droit document:u).
Strictly additive. The files already attached are never touched, and there is no way to remove one — that is deliberate, not an oversight.
All or nothing. Every file is checked before a single byte reaches S3: one refused extension and the whole call fails, leaving the document exactly as it was. The stored media type is derived from the extension and never from the multipart header, which the caller controls.
A file whose name is already attached to this document is refused (409 duplicate_attachment): storing it would overwrite the first, which nothing could then
bring back. A document the company received carries no attachment (409).
Attaching is not a correction: it changes nothing of what the document says, so it stays possible on a document already sent or already handed to the accounting — the same reasoning that lets a payment through. In sandbox mode the files are validated exactly as in live mode but nothing is uploaded nor stored.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Body
The files to attach. Allowed extensions: .pdf, .csv, .png, .jpg, .jpeg, .xlsx, .ods — up to 10 per call, 10 MB for the whole call.
Response
Successful Response
A document of the company: an invoice/credit note it issued or a document it
received (purchase invoice, credit note, other). The source table is hidden — the
client sees a single unified document identified by an opaque id.
Monetary amounts are decimal numbers in the document's currency. They may be null
when the document could not be parsed automatically, or for other_document types
that have no financial breakdown.
Both sources are normalised to this shape by the repository adapters; the validators below map the internal codes to their public values.
Opaque unique identifier of the document.
Document type. One of: sale_invoice, sale_credit_note, purchase_invoice, purchase_credit_note, other_document, unknown.
Channel the document came in through. One of: fidly (generated in Fidly), manual, peppol, mail, odoo, billit, api (or unknown).
The document's own number (e.g. invoice number).
Purchase/sales order number referenced by the document.
Reference of the despatch advice (delivery note) related to the document.
Reference given by the buyer, to be quoted back on the document (e.g. a cost centre).
Date the document was issued (ISO YYYY-MM-DD).
Payment due date (ISO YYYY-MM-DD).
Date the VAT becomes chargeable, when it differs from the issue date (ISO YYYY-MM-DD).
Date the goods/services were actually delivered (ISO YYYY-MM-DD).
First day of the period the document bills (ISO YYYY-MM-DD).
Last day of the period the document bills (ISO YYYY-MM-DD).
Communication to quote when paying the document. null when the document carries none.
true when payment_remittance is a structured communication (a bank-checked reference such as a Belgian OGM/VCS) rather than free text. Always true for documents issued by Fidly.
Timestamp the document was created in Fidly (ISO 8601). May be null on rare legacy rows where it was never set.
ISO 4217 currency code of all amounts (e.g. EUR).
Total amount excluding tax.
Total tax (VAT) amount.
Total amount payable, tax included.
Amount already paid.
Amount still to be paid (total_amount minus paid_amount).
Payment state. One of: unpaid, partial, paid (or unknown).
Accounting workflow state. One of: waiting, accepted, transfered, exported, export_error, imported, validated, hidden, exporting, posting, posting_error, deleted (or unknown).
true if a PDF is stored for this document (retrievable via the file endpoint).
true if a structured XML version (e.g. Peppol/UBL) is stored for this document.
Nature of relation_id: company (a registered business relation) or contact (an individual contact). null when there is no linked third party.
Opaque identifier of the third party the document is linked to (resolvable via GET /relations/{id}). Its nature is given by relation_type. null when the document has no linked third party.
Opaque identifier of the journal the document is booked in (resolvable via GET /journals/{id}). null when the document has no linked journal.
Opaque identifier of the saved delivery address the document is delivered to (resolvable via GET /delivery-locations/{id}). null when none is set.
Payment terms the due_date follows from, as <days>-<basis> (e.g. 30-df). Always null on a received document: only documents Fidly issues carry them.
Legal mention printed at the bottom of the document (e.g. a VAT exemption wording). Always null on received documents.
Peppol send state of an issued document. One of: not_sent, sending, sent (delivered to the network), accepted (acknowledged by the recipient), rejected (refused by the recipient), failed (or unknown). rejected and failed can be sent again. Always null on a received document.
E-mail send state of an issued document. One of: not_sent, sent, failed (or unknown). Always null on a received document.
Files attached to the document, in the order they were added. Attach one with POST /documents/{id}/attachments; the API offers no way to remove one. A received document never carries any.
Discounts/surcharges applied to the document as a whole, after the lines and their own. tax_exclusive_amount is already net of them.
Detailed lines of the document (invoiced items/services). Empty when none are stored.