> ## Documentation Index > Fetch the complete documentation index at: https://api-doc.fidly.be/llms.txt > Use this file to discover all available pages before exploring further. # List Documents ## OpenAPI ````yaml /openapi.json get /documents openapi: 3.1.0 info: title: Fidly API version: 1.0.0 servers: - url: https://api.fidly.be description: Production security: [] paths: /documents: get: tags: - documents summary: List Documents operationId: list_documents_documents_get parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Max items returned (1-100). default: 50 title: Limit description: Max items returned (1-100). - name: offset in: query required: false schema: type: integer maximum: 10000 minimum: 0 description: Number of items to skip (pagination). Capped at 10000. default: 0 title: Offset description: Number of items to skip (pagination). Capped at 10000. - name: origin in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter by origin. Comma-separated list also accepted = match any (IN). title: Origin description: >- Filter by origin. Comma-separated list also accepted = match any (IN). - name: type in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter by document type. Comma-separated list also accepted = match any (IN). title: Type description: >- Filter by document type. Comma-separated list also accepted = match any (IN). - name: accounting_status in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter by accounting status. Comma-separated list also accepted = match any (IN). title: Accounting Status description: >- Filter by accounting status. Comma-separated list also accepted = match any (IN). - name: payment_status in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter by payment status. Comma-separated list also accepted = match any (IN). title: Payment Status description: >- Filter by payment status. Comma-separated list also accepted = match any (IN). - name: issue_date_from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: >- Keep documents whose issue_date is on or after this date (YYYY-MM-DD). title: Issue Date From description: >- Keep documents whose issue_date is on or after this date (YYYY-MM-DD). - name: issue_date_to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: >- Keep documents whose issue_date is on or before this date (YYYY-MM-DD). title: Issue Date To description: >- Keep documents whose issue_date is on or before this date (YYYY-MM-DD). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Page_DocumentOut_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: Page_DocumentOut_: properties: items: items: $ref: '#/components/schemas/DocumentOut' type: array title: Items total: type: integer title: Total limit: type: integer title: Limit offset: type: integer title: Offset type: object required: - items - total - limit - offset title: Page[DocumentOut] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError DocumentOut: properties: id: type: string title: Id description: Opaque unique identifier of the document. type: type: string title: Type description: >- Document type. One of: `sale_invoice`, `sale_credit_note`, `purchase_invoice`, `purchase_credit_note`, `other_document`, `unknown`. origin: type: string title: Origin description: >- Channel the document came in through. One of: `fidly` (generated in Fidly), `manual`, `peppol`, `mail`, `odoo`, `billit`, `api` (or `unknown`). relation_type: anyOf: - type: string - type: 'null' title: Relation Type description: >- Nature of `relation_id`: `company` (a registered business relation) or `contact` (an individual contact). `null` when there is no linked third party. relation_id: anyOf: - type: string - type: 'null' title: Relation Id description: >- 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. journal_id: anyOf: - type: string - type: 'null' title: Journal Id description: >- Opaque identifier of the journal the document is booked in (resolvable via `GET /journals/{id}`). `null` when the document has no linked journal. delivery_location_id: anyOf: - type: string - type: 'null' title: Delivery Location Id description: >- Opaque identifier of the saved delivery address the document is delivered to (resolvable via `GET /delivery-locations/{id}`). `null` when none is set. document_number: anyOf: - type: string - type: 'null' title: Document Number description: The document's own number (e.g. invoice number). order_number: anyOf: - type: string - type: 'null' title: Order Number description: Purchase/sales order number referenced by the document. despatch_reference: anyOf: - type: string - type: 'null' title: Despatch Reference description: >- Reference of the despatch advice (delivery note) related to the document. buyer_reference: anyOf: - type: string - type: 'null' title: Buyer Reference description: >- Reference given by the buyer, to be quoted back on the document (e.g. a cost centre). issue_date: anyOf: - type: string format: date - type: 'null' title: Issue Date description: Date the document was issued (ISO `YYYY-MM-DD`). due_date: anyOf: - type: string format: date - type: 'null' title: Due Date description: Payment due date (ISO `YYYY-MM-DD`). payment_terms: anyOf: - type: string - type: 'null' title: Payment Terms description: >- Payment terms the `due_date` follows from, as `-` (e.g. `30-df`). Always `null` on a received document: only documents Fidly issues carry them. tax_point_date: anyOf: - type: string format: date - type: 'null' title: Tax Point Date description: >- Date the VAT becomes chargeable, when it differs from the issue date (ISO `YYYY-MM-DD`). delivery_date: anyOf: - type: string format: date - type: 'null' title: Delivery Date description: Date the goods/services were actually delivered (ISO `YYYY-MM-DD`). period_start: anyOf: - type: string format: date - type: 'null' title: Period Start description: First day of the period the document bills (ISO `YYYY-MM-DD`). period_end: anyOf: - type: string format: date - type: 'null' title: Period End description: Last day of the period the document bills (ISO `YYYY-MM-DD`). legal_notice: anyOf: - type: string - type: 'null' title: Legal Notice description: >- Legal mention printed at the bottom of the document (e.g. a VAT exemption wording). Always `null` on received documents. payment_remittance: anyOf: - type: string - type: 'null' title: Payment Remittance description: >- Communication to quote when paying the document. `null` when the document carries none. is_remittance_structured: type: boolean title: Is Remittance Structured description: >- `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. create_date: anyOf: - type: string format: date-time - type: 'null' title: Create Date description: >- Timestamp the document was created in Fidly (ISO 8601). May be `null` on rare legacy rows where it was never set. currency: anyOf: - type: string - type: 'null' title: Currency description: ISO 4217 currency code of all amounts (e.g. `EUR`). tax_exclusive_amount: anyOf: - type: number - type: 'null' title: Tax Exclusive Amount description: Total amount excluding tax. tax_amount: anyOf: - type: number - type: 'null' title: Tax Amount description: Total tax (VAT) amount. total_amount: anyOf: - type: number - type: 'null' title: Total Amount description: Total amount payable, tax included. paid_amount: anyOf: - type: number - type: 'null' title: Paid Amount description: Amount already paid. remaining_amount: anyOf: - type: number - type: 'null' title: Remaining Amount description: Amount still to be paid (`total_amount` minus `paid_amount`). payment_status: type: string title: Payment Status description: 'Payment state. One of: `unpaid`, `partial`, `paid` (or `unknown`).' accounting_status: type: string title: Accounting Status description: >- Accounting workflow state. One of: `waiting`, `accepted`, `transfered`, `exported`, `export_error`, `imported`, `validated`, `hidden`, `exporting`, `posting`, `posting_error`, `deleted` (or `unknown`). pdf_available: type: boolean title: Pdf Available description: >- `true` if a PDF is stored for this document (retrievable via the file endpoint). xml_available: type: boolean title: Xml Available description: >- `true` if a structured XML version (e.g. Peppol/UBL) is stored for this document. peppol_status: anyOf: - type: string - type: 'null' title: Peppol Status description: >- 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. mail_status: anyOf: - type: string - type: 'null' title: Mail Status description: >- E-mail send state of an issued document. One of: `not_sent`, `sent`, `failed` (or `unknown`). Always `null` on a received document. attachments: items: $ref: '#/components/schemas/AttachmentOut' type: array title: Attachments description: >- 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. allowance_charges: items: $ref: '#/components/schemas/AllowanceChargeOut' type: array title: Allowance Charges description: >- Discounts/surcharges applied to the document as a whole, after the lines and their own. `tax_exclusive_amount` is already net of them. lines: items: $ref: '#/components/schemas/LineOut' type: array title: Lines description: >- Detailed lines of the document (invoiced items/services). Empty when none are stored. additionalProperties: true type: object required: - id - type - origin - document_number - order_number - despatch_reference - buyer_reference - issue_date - due_date - tax_point_date - delivery_date - period_start - period_end - payment_remittance - is_remittance_structured - create_date - currency - tax_exclusive_amount - tax_amount - total_amount - paid_amount - remaining_amount - payment_status - accounting_status - pdf_available - xml_available title: DocumentOut description: >- 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. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError AttachmentOut: properties: filename: anyOf: - type: string - type: 'null' title: Filename description: Name of the attached file. mimetype: anyOf: - type: string - type: 'null' title: Mimetype description: Media type of the attached file. type: object title: AttachmentOut description: >- A file attached to a document. Where it is stored (bucket and key) stays internal. AllowanceChargeOut: properties: code: anyOf: - type: string - type: 'null' title: Code description: Reason code for the allowance/charge. type: anyOf: - type: string - type: 'null' title: Type description: '`allowance` (discount) or `charge` (surcharge).' amount: anyOf: - type: number - type: 'null' title: Amount description: Monetary amount of the allowance/charge. reason: anyOf: - type: string - type: 'null' title: Reason description: Free-text reason. rate: anyOf: - type: number - type: 'null' title: Rate description: Percentage rate, when expressed as a percentage. type: object title: AllowanceChargeOut description: A discount (allowance) or surcharge (charge) applied to a document line. LineOut: properties: sequence: anyOf: - type: integer - type: 'null' title: Sequence description: Position of the line within the document. quantity: anyOf: - type: number - type: 'null' title: Quantity description: Quantity of the item. vat_rate: anyOf: - type: number - type: 'null' title: Vat Rate description: >- VAT rate applied to the line, in percent. Always `null` on a `not_subject` line: outside the scope of VAT there is no rate at all (Peppol BR-O-05). item_name: anyOf: - type: string - type: 'null' title: Item Name description: Name of the item/service. item_description: anyOf: - type: string - type: 'null' title: Item Description description: Longer description of the item/service. unit_price: anyOf: - type: number - type: 'null' title: Unit Price description: Price for one unit, before tax. unit_code: anyOf: - type: string - type: 'null' title: Unit Code description: Unit of measure code (e.g. `C62` for unit). vat_code: anyOf: - type: string - type: 'null' title: Vat Code description: >- VAT regime of the line: `standard`, `exempted`, `zero_rated`, `reverse_charge`, `intra_community`, `export` or `not_subject`. Legacy documents may carry the reserved `transferred_vat`, `canary_islands` or `ceuta_melilla`. subtotal: anyOf: - type: number - type: 'null' title: Subtotal description: Line amount before discounts, excluding tax. total: anyOf: - type: number - type: 'null' title: Total description: Line amount after discounts, excluding tax. tax_amount: anyOf: - type: number - type: 'null' title: Tax Amount description: Tax (VAT) amount of the line. section_name: anyOf: - type: string - type: 'null' title: Section Name description: Title of the section this line belongs to, if any. item_properties: anyOf: - additionalProperties: true type: object - type: 'null' title: Item Properties description: Free key/value item properties, kept as-is. item_identification: anyOf: - type: string - type: 'null' title: Item Identification description: Standard item identifier (e.g. GTIN). product_code: anyOf: - type: string - type: 'null' title: Product Code description: Seller's own product code. allowance_charges: items: $ref: '#/components/schemas/AllowanceChargeOut' type: array title: Allowance Charges description: Discounts/surcharges applied to this line. type: object title: LineOut description: A single line of a document (one invoiced item/service). securitySchemes: HTTPBearer: type: http scheme: bearer ````