Filtern und Paginieren

Suchanfragen für Belege, Kontakte, Bankkonten, Umsätze, Buchungen, Rechnungsentwürfe, Buchungsvorlagen, Dauerbuchungen und Mails im Belegpostfach.

Listen fragst du mit POST an eine Filterroute ab, zum Beispiel POST /api/document/filter. Der Body ist JSON und enthält einen Filterausdruck, die Sortierung und die Seite. Alle Filterrouten stehen weiter unten.

Beispiel für POST /api/document/filter:

{
  "kind": "and",
  "children": [
    {
      "kind": "range",
      "attribute": "invoiceDate",
      "lower": "2026-01-01",
      "upper": "2026-12-31"
    }
  ],
  "limit": 50,
  "offset": 0,
  "sort": [
    "invoiceDate"
  ],
  "direction": [
    "desc"
  ]
}

Welche Attribute es je Route gibt, steht dort, jeweils mit einem Beispiel.

Filterausdruck

Ein Ausdruck hat eine Art (kind). Ausdrücke mit and, or und not enthalten weitere Ausdrücke in children und lassen sich verschachteln.

Art (`kind`)	Bedeutung
`and`	Alle Teilausdrücke in `children` treffen zu. Ein leeres `children` liefert alle Einträge.
`or`	Mindestens ein Teilausdruck in `children` trifft zu.
`eq`	`attribute` hat genau den Wert `value`.
`not`	Verneint die Teilausdrücke in `children`, mindestens einen. Mehrere verneint es gemeinsam, wie ein `not` um ein `and`.
`in`	`attribute` enthält den Text `value`. Groß- und Kleinschreibung spielen keine Rolle.
`range`	`attribute` liegt zwischen `lower` und `upper`, beide Grenzen inklusive. Eine Grenze genügt.
`oneof`	`attribute` hat einen der Werte im Array `value`.

Werte sind Strings, Zahlen oder Wahrheitswerte. Kalenderdaten (Typ date) schreibst du als String JJJJ-MM-TT, Zeitpunkte (Typ date-time) als String nach RFC 3339 mit Zeitzone. Einzelheiten stehen unter Datentypen.
{ "kind": "and", "children": [] } liefert alle Einträge.
not braucht mindestens einen Ausdruck in children. Mehrere verneint es gemeinsam, wie ein not um ein and.
Eine unbekannte Art (kind) oder ein unbekanntes Attribut ergibt 400.
Ein Wert, der nicht zum Typ des Attributs passt, ergibt ebenfalls 400, zum Beispiel Text für eine Ganzzahl oder eine UUID, eine Zahl mit Nachkommastellen für eine Ganzzahl oder ein Zeitpunkt in einer Schreibweise außerhalb von ISO 8601, etwa 01.09.2026. Kalenderdaten in anderer Schreibweise lehnt die API nicht ab, sie liefern aber falsche Treffer.

Sortieren

sort enthält ein oder mehrere Attribute, direction die Richtung je Attribut: asc (Standard) oder desc. Beide Felder nehmen auch einen einzelnen String an.

Für sort sind nur die Attribute dokumentiert, die weiter unten als sortierbar markiert sind. Ein Attribut, das dort als nicht sortierbar markiert ist, etwa uploadDocument.ocrStatus bei Belegen, ergibt in sort den Status 400.

Ohne sort ist die Reihenfolge nicht festgelegt. Sortiere immer, wenn du mehrere Seiten abrufst.

Seitenweise abrufen

Feld	Bedeutung
`limit`	Treffer je Seite, höchstens 1.000. Größere Werte werden auf den Höchstwert gesetzt. Ohne `limit` gilt der Höchstwert.
`offset`	Anzahl der Treffer, die übersprungen werden, höchstens 1.000.000. Größere oder negative Werte ergeben `400`.

Die Antwort nennt die Gesamtzahl und die gelieferte Seite:

{
  "total": 1234,
  "limit": 100,
  "offset": 0,
  "items": []
}

Für die nächste Seite erhöhst du offset um limit, bis offset die Zahl total erreicht. Wenn sich die Daten zwischen zwei Abrufen ändern, können sich Seiten verschieben. Für einen vollständigen Abgleich grenzt du deshalb am besten über ein Datumsattribut ein, sortierst danach und rufst die Seiten zügig nacheinander ab.

Gelöschte Einträge

Ohne weitere Angabe liefern die Filterrouten nur Einträge, die nicht gelöscht sind. Bei Belegen, Kontakten, Bankkonten, Umsätzen und Buchungen kommen mit "includeDeleted": true im Body gelöschte dazu. Sie tragen in deletedAt den Zeitpunkt, seit dem sie als gelöscht gelten; bei allen anderen ist deletedAt null. Nach deletedAt filterst und sortierst du wie nach jedem anderen Zeitpunkt, etwa für den Delta-Sync:

{
  "includeDeleted": true,
  "kind": "range",
  "attribute": "deletedAt",
  "lower": "2026-09-27T08:00:00Z",
  "sort": ["deletedAt", "id"],
  "limit": 1000
}

Ohne includeDeleted findet ein Filter auf deletedAt nur Einträge mit null.
Rechnungsentwürfe, Buchungsvorlagen, Dauerbuchungen und Mails liefern auch mit includeDeleted keine gelöschten Einträge. Buchungsvorlagen, Dauerbuchungen und Mails haben kein deletedAt, Mails auch kein updatedAt.
Manche Belege entfernt bimetrics beim Löschen nicht, etwa solche mit festgeschriebenen Buchungen. In der API gelten sie trotzdem ab dann als gelöscht, mit dem Zeitpunkt der Löschung in deletedAt.
Einzeln abrufen lassen sich gelöschte Einträge nicht: GET /api/document/{id} und die anderen Routen mit ID antworten mit 404.

Attribute je Route

Dokumentiert sind nur die hier aufgeführten Attribute, in sort nur die als sortierbar markierten. Andere Attribute können funktionieren, gehören aber nicht zum dokumentierten Umfang (siehe Stabilität und Änderungen) und können sich ohne Ankündigung ändern.

Kontakte findest du auch über den Ort ihrer Anschriften: { "kind": "in", "attribute": "addresses.city", "value": "freiburg" } findet jeden Kontakt mit einer Anschrift in Freiburg.

Buchungen suchen

POST /api/accounting/booking/filter · Referenz

Attribut	Typ	Sortierbar	Beschreibung
`id`	uuid	ja	ID der Buchung.
`bookingDate`	date	ja	Buchungsdatum.
`account`	integer	ja	Konto.
`accountContra`	integer	ja	Gegenkonto.
`amount`	decimal	ja	Betrag.
`refDocumentId`	uuid	ja	ID des gebuchten Belegs.
`refBankTransactionId`	uuid	ja	ID des gebuchten Umsatzes.
`costCenterId`	uuid	ja	Kostenstelle oder Verteilung der Buchung; nur Buchungen mit Aufwands- oder Erlöskonto tragen sie. Als Filter findet nur die ID der Verteilung eine Buchung mit Verteilung, nicht die ID einer ihrer Kostenstellen; die Beträge je Kostenstelle nennt `costCenterParts`.
`finalized`	date-time	ja	Zeitpunkt der Festschreibung; `null` bei nicht festgeschriebenen Buchungen.
`updatedAt`	date-time	ja	Zeitpunkt der letzten Änderung.
`deletedAt`	date-time	ja	Zeitpunkt, seit dem der Eintrag als gelöscht gilt; `null`, solange er nicht gelöscht ist. Gelöschte Einträge liefert die Suche nur mit `includeDeleted`. Für Abgleiche per Polling: `includeDeleted` und `range` mit `lower` = `deletedAt` des zuletzt gelesenen gelöschten Eintrags minus 5 Minuten Überlappung, sortiert nach `deletedAt`.

{
  "kind": "and",
  "children": [
    {
      "kind": "range",
      "attribute": "bookingDate",
      "lower": "2026-01-01",
      "upper": "2026-12-31"
    }
  ],
  "limit": 50,
  "offset": 0,
  "sort": [
    "bookingDate"
  ],
  "direction": [
    "desc"
  ]
}

Bankkonten suchen

POST /api/bankaccount/filter · Referenz

Attribut	Typ	Sortierbar	Beschreibung
`id`	uuid	ja	ID des Bankkontos.
`iban`	string	ja	IBAN des Kontos.
`bankName`	string	ja	Name der Bank.
`ownerName`	string	ja	Name des Kontoinhabers laut Bank.
`currency`	string	ja	Kontowährung (ISO 4217).
`disabled`	boolean	ja	Konto ist deaktiviert.
`updatedAt`	date-time	ja	Zeitpunkt der letzten Änderung.
`deletedAt`	date-time	ja	Zeitpunkt, seit dem der Eintrag als gelöscht gilt; `null`, solange er nicht gelöscht ist. Gelöschte Einträge liefert die Suche nur mit `includeDeleted`. Für Abgleiche per Polling: `includeDeleted` und `range` mit `lower` = `deletedAt` des zuletzt gelesenen gelöschten Eintrags minus 5 Minuten Überlappung, sortiert nach `deletedAt`.

{
  "kind": "and",
  "children": [
    {
      "kind": "range",
      "attribute": "updatedAt",
      "lower": "2026-01-01T00:00:00Z",
      "upper": "2026-12-31T23:59:59Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "sort": [
    "updatedAt"
  ],
  "direction": [
    "desc"
  ]
}

Umsätze suchen

POST /api/banktransaction/filter · Referenz

Attribut	Typ	Sortierbar	Beschreibung
`id`	uuid	ja	ID des Umsatzes.
`bankAccountId`	uuid	ja	ID des Bankkontos.
`bookingDate`	date	ja	Buchungstag.
`valueDate`	date	ja	Wertstellung.
`transactionAmount`	integer	ja	Betrag in Cent, negativ bei Ausgängen.
`otherPartyName`	string	ja	Name der Gegenseite.
`remittanceInformation`	string	ja	Verwendungszweck.
`status`	string	ja	`booked` (gebucht) oder `pending` (vorgemerkt).
`updatedAt`	date-time	ja	Zeitpunkt der letzten Änderung, auch einer Zuordnung (`match`).
`deletedAt`	date-time	ja	Zeitpunkt, seit dem der Eintrag als gelöscht gilt; `null`, solange er nicht gelöscht ist. Gelöschte Einträge liefert die Suche nur mit `includeDeleted`. Für Abgleiche per Polling: `includeDeleted` und `range` mit `lower` = `deletedAt` des zuletzt gelesenen gelöschten Eintrags minus 5 Minuten Überlappung, sortiert nach `deletedAt`.

{
  "kind": "and",
  "children": [
    {
      "kind": "range",
      "attribute": "bookingDate",
      "lower": "2026-01-01",
      "upper": "2026-12-31"
    }
  ],
  "limit": 50,
  "offset": 0,
  "sort": [
    "bookingDate"
  ],
  "direction": [
    "desc"
  ]
}

Kontakte suchen

POST /api/contact/filter · Referenz

Attribut	Typ	Sortierbar	Beschreibung
`id`	uuid	ja	ID des Kontakts.
`companyName`	string	ja	Name des Kontakts.
`customerNumber`	integer	ja	Kunden- bzw. Lieferantennummer.
`type`	string	ja	Art: `customer` (Kunde), `supplier` (Lieferant) oder `partner`.
`customerKind`	string	ja	Steuerlich: `business` (Unternehmen) oder `private` (Privatperson); leer, wenn unbekannt.
`contactInfo.email`	string	ja	E-Mail-Adresse.
`paymentInfo.iban`	string	ja	IBAN.
`paymentInfo.vatId`	string	ja	USt-IdNr.
`addresses.city`	string	nein	Orte der Anschriften des Kontakts; suche mit `in` nach einem Teil davon.
`updatedAt`	date-time	ja	Zeitpunkt der letzten Änderung.
`deletedAt`	date-time	ja	Zeitpunkt, seit dem der Eintrag als gelöscht gilt; `null`, solange er nicht gelöscht ist. Gelöschte Einträge liefert die Suche nur mit `includeDeleted`. Für Abgleiche per Polling: `includeDeleted` und `range` mit `lower` = `deletedAt` des zuletzt gelesenen gelöschten Eintrags minus 5 Minuten Überlappung, sortiert nach `deletedAt`.
`externalRef`	string	ja	Externe Kunden- oder Lieferantenreferenz.

{
  "kind": "and",
  "children": [
    {
      "kind": "range",
      "attribute": "updatedAt",
      "lower": "2026-01-01T00:00:00Z",
      "upper": "2026-12-31T23:59:59Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "sort": [
    "updatedAt"
  ],
  "direction": [
    "desc"
  ]
}

Dauerbuchungen suchen

POST /api/document/collection/contract/filter · Referenz

Attribut	Typ	Sortierbar	Beschreibung
`id`	uuid	ja	ID der Dauerbuchung.
`friendlyName`	string	ja	Bezeichnung.
`collectionNumber`	string	ja	Nummer der Dauerbuchung.
`kind`	string	ja	Art der erzeugten Belege: `receipt` (Eingangsbeleg) oder `invoice` (Ausgangsrechnung).
`issuer.name`	string	ja	Name des Ausstellers der erzeugten Belege.
`recipient.name`	string	ja	Name des Empfängers der erzeugten Belege.
`updatedAt`	date-time	ja	Zeitpunkt der letzten Änderung.

{
  "kind": "and",
  "children": [
    {
      "kind": "range",
      "attribute": "updatedAt",
      "lower": "2026-01-01T00:00:00Z",
      "upper": "2026-12-31T23:59:59Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "sort": [
    "updatedAt"
  ],
  "direction": [
    "desc"
  ]
}

Buchungsvorlagen suchen

POST /api/document/collection/series/filter · Referenz

Attribut	Typ	Sortierbar	Beschreibung
`id`	uuid	ja	ID der Buchungsvorlage.
`friendlyName`	string	ja	Bezeichnung.
`collectionNumber`	string	ja	Nummer der Buchungsvorlage.
`kind`	string	ja	Art der erzeugten Belege: `receipt` (Eingangsbeleg) oder `invoice` (Ausgangsrechnung).
`issuer.name`	string	ja	Name des Ausstellers der erzeugten Belege.
`recipient.name`	string	ja	Name des Empfängers der erzeugten Belege.
`systemTemplateId`	uuid	ja	ID der Standardvorlage von bimetrics; `null` bei eigenen Vorlagen.
`updatedAt`	date-time	ja	Zeitpunkt der letzten Änderung.

{
  "kind": "and",
  "children": [
    {
      "kind": "range",
      "attribute": "updatedAt",
      "lower": "2026-01-01T00:00:00Z",
      "upper": "2026-12-31T23:59:59Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "sort": [
    "updatedAt"
  ],
  "direction": [
    "desc"
  ]
}

Belege suchen

POST /api/document/filter · Referenz

Attribut	Typ	Sortierbar	Beschreibung
`id`	uuid	ja	ID des Belegs.
`kind`	string	ja	Belegart: `invoice` (Ausgangsrechnung) oder `receipt` (Eingangsbeleg).
`kindReview`	boolean	ja	„Belegtyp prüfen“: `true` findet Belege, deren Belegtyp noch jemand wählen muss.
`invoiceDate`	date	ja	Rechnungsdatum.
`invoiceNumber`	string	ja	Rechnungsnummer.
`issuer.name`	string	ja	Name des Ausstellers.
`recipient.name`	string	ja	Name des Empfängers.
`uploadDocument.ocrStatus`	string	nein	Stand der Erkennung: `pending`, `processing`, `success`, `failed` oder `quota_paused`.
`costCenterId`	uuid	ja	Kostenstelle oder Verteilung des Belegs. `eq` mit `null` findet Belege ohne Kostenstelle.
`createdAt`	date-time	ja	Zeitpunkt der Anlage in bimetrics.
`updatedAt`	date-time	ja	Zeitpunkt der letzten Änderung, auch einer Zuordnung (`match`). Für Abgleiche per Polling: `range` mit `lower` = `updatedAt` des zuletzt gelesenen Belegs minus 5 Minuten Überlappung, sortiert nach `updatedAt`; Belege nach `id` speichern, weil manche doppelt kommen. Gelöschte Belege findet dieser Abgleich nicht, siehe `deletedAt`.
`deletedAt`	date-time	ja	Zeitpunkt, seit dem der Eintrag als gelöscht gilt; `null`, solange er nicht gelöscht ist. Gelöschte Einträge liefert die Suche nur mit `includeDeleted`. Für Abgleiche per Polling: `includeDeleted` und `range` mit `lower` = `deletedAt` des zuletzt gelesenen gelöschten Eintrags minus 5 Minuten Überlappung, sortiert nach `deletedAt`. Auch ein Beleg, den bimetrics beim Löschen behält, etwa wegen festgeschriebener Buchungen, gilt ab dann als gelöscht.

{
  "kind": "and",
  "children": [
    {
      "kind": "range",
      "attribute": "invoiceDate",
      "lower": "2026-01-01",
      "upper": "2026-12-31"
    }
  ],
  "limit": 50,
  "offset": 0,
  "sort": [
    "invoiceDate"
  ],
  "direction": [
    "desc"
  ]
}

Rechnungsentwürfe suchen

POST /api/draft/filter · Referenz

Attribut	Typ	Sortierbar	Beschreibung
`id`	uuid	ja	ID des Entwurfs.
`deletedAt`	date-time	ja	Immer `null`: Gelöschte Entwürfe liefert die Suche nicht, auch nicht mit `includeDeleted`.
`invoiceNumber`	string	ja	Arbeits- oder Rechnungsnummer.
`externalRef`	string	ja	Externe Bestell- oder Integrationsreferenz.
`kind`	string	ja	invoice, proposal, order_confirmation, cancellation, invoice_correction oder correction_reversal.
`sourceSalesProposalId`	uuid	ja	Ursprüngliches Angebot.
`sourceOrderConfirmationId`	uuid	ja	Ausdrücklich gewählte finale AB als Rechnungsquelle.
`updatedAt`	date-time	ja	Letzte Änderung; als expectedUpdatedAt für einen Schreibaufruf verwenden.
`invoiceRole`	string	ja	Rolle im Auftrag: `down_payment` (Abschlag) oder `final` (Schlussrechnung); leer bei allen anderen Entwürfen.

{
  "kind": "and",
  "children": [
    {
      "kind": "range",
      "attribute": "deletedAt",
      "lower": "2026-01-01T00:00:00Z",
      "upper": "2026-12-31T23:59:59Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "sort": [
    "deletedAt"
  ],
  "direction": [
    "desc"
  ]
}

Mails suchen

POST /api/email/inbox/item/ · Referenz

Attribut	Typ	Sortierbar	Beschreibung
`id`	uuid	ja	ID der Mail.
`date`	date-time	ja	Datum der Mail.
`archived`	date-time	ja	Seit wann die Mail unter „Erledigt“ steht; `null` unter „Offen“.
`sender`	string	ja	Absender.
`subject`	string	ja	Betreff.
`attachments.preselected`	boolean	nein	Vorgeschlagener Anhang.
`attachments.savedAsDocumentId`	uuid	nein	Beleg, der aus einem Anhang wurde; `null`, solange er nicht übernommen ist.

{
  "kind": "and",
  "children": [
    {
      "kind": "range",
      "attribute": "date",
      "lower": "2026-01-01T00:00:00Z",
      "upper": "2026-12-31T23:59:59Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "sort": [
    "date"
  ],
  "direction": [
    "desc"
  ]
}