Skip to content
HALOWERK

Formatwerk

retention label

Step 1, classification: each document gets the given type or, from its title and file name, a class from a transparent German/English keyword rule set (e.g. Rechnung/Gutschrift/invoice, Kontoauszug/Quittung/Abrechnung/receipt, Lieferschein, Jahresabschluss/Bilanz, Lagebericht, Inventur, Hauptbuch/Kassenbuch/journal, Verfahrensdokumentation, Zollanmeldung, Angebot/Vertrag/Mahnung/E-Mail as business letters) with matched terms, alternatives and an ambiguity flag; unmatched documents are listed.

POST https://format.halowerk.com/v1/retention-label

Inputs

Fields of the published input schema
FieldTypeRequiredDescription
documentsarrayYes
merchantbooleanNoThe organisation is a merchant (Kaufmann) and subject to § 257 HGB.
institutionbooleanNoCredit, insurance or securities institution (KWG § 1 Abs. 1b, VAG § 1 Abs. 1, WpIG § 2 Abs. 1).
as_ofstringNoReference date for "deletable" (default today, UTC).
Show full input schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "documents"
  ],
  "properties": {
    "documents": {
      "type": "array",
      "minItems": 1,
      "maxItems": 1000,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "date"
        ],
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 200
          },
          "title": {
            "type": "string",
            "maxLength": 300,
            "description": "Document title or subject, used for classification when type is missing."
          },
          "filename": {
            "type": "string",
            "maxLength": 300,
            "description": "File name, used for classification when type is missing."
          },
          "type": {
            "type": "string",
            "enum": [
              "books",
              "inventory",
              "opening_balance",
              "annual_financial_statements",
              "management_report",
              "consolidated_statements",
              "organisational_documents",
              "booking_voucher",
              "invoice",
              "business_letter_received",
              "business_letter_sent",
              "customs_documents",
              "other_tax_relevant",
              "delivery_note_received",
              "delivery_note_sent"
            ],
            "description": "Retention class if already known (skips classification)."
          },
          "direction": {
            "type": "string",
            "enum": [
              "received",
              "sent"
            ],
            "description": "For letters and delivery notes."
          },
          "date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "Date of the triggering event (created, received, sent, last entry, approved)."
          },
          "invoice_date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "For delivery notes: date the invoice was received or sent."
          },
          "hold_until": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "Legal hold (open assessment, audit, litigation) until this date."
          }
        }
      }
    },
    "merchant": {
      "type": "boolean",
      "default": true,
      "description": "The organisation is a merchant (Kaufmann) and subject to § 257 HGB."
    },
    "institution": {
      "type": "boolean",
      "default": false,
      "description": "Credit, insurance or securities institution (KWG § 1 Abs. 1b, VAG § 1 Abs. 1, WpIG § 2 Abs. 1)."
    },
    "as_of": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Reference date for \"deletable\" (default today, UTC)."
    }
  }
}

Open original schema

Published input example

{
  "documents": [
    {
      "id": "DMS-1",
      "title": "Eingangsrechnung RE-2025-001",
      "date": "2025-03-15"
    },
    {
      "id": "DMS-2",
      "filename": "Kontoauszug_2016-03.pdf",
      "date": "2016-03-31"
    }
  ]
}

Result & documentation

Machine-readable documentation of this hub

Source of this page: the published HALOWERK catalog. Updated: 2026-11-17 UTC.

More endpoints in this hub

All endpoints in this hub →