Kontakte suchen
Benötigte Berechtigung:contacts:read(Kontakte lesen)
Sucht Kontakte (Kunden und Lieferanten) der Firma mit einem Filter und liefert eine Seite der Treffer.
Benötigt einen Schlüssel mit der Berechtigung contacts:read oder read.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
Filter, Sortierung und Seite. Dokumentierte Filterattribute: x-bimetrics-filter.
application/json- body
Suche mit Filter, Sortierung und Seiten. Der Filterausdruck steht auf oberster Ebene; {} liefert alle Einträge.
attribute?stringFilterattribut für eq, in, range und oneof, siehe x-bimetrics-filter der Operation. Groß-/Kleinschreibung und Punkte werden ignoriert.
children?array<>Teilfilter für and, or und not.
direction?|array<>Richtung je Eintrag in sort; Standard asc.
includeDeleted?booleantrue liefert auch gelöschte Einträge, erkennbar an deletedAt, aber nur bei Belegen, Kontakten, Bankkonten, Umsätzen und Buchungen; die übrigen Suchrouten ignorieren das Feld. Ohne das Feld oder mit false nur Einträge, die nicht gelöscht sind. Für Abgleiche von Löschungen mit range auf deletedAt, siehe Delta-Sync.
falsekind?stringArt des Filters: and/or verknüpfen children, not verneint children, eq vergleicht attribute mit value (null prüft auf leer), in sucht value als Text im Attribut (enthält, ohne Groß-/Kleinschreibung), range prüft lower ≤ Attribut ≤ upper (eine Grenze genügt), oneof prüft, ob das Attribut einem Wert der Liste value entspricht. Leer: alle Einträge.
"""and""or""eq""not""in""range""oneof"limit?integerTreffer je Seite. Standard und Höchstwert 1000; größere Werte werden auf 1000 begrenzt.
0 <= value1000lower?unknownUntergrenze für range, einschließlich.
offset?integerAnzahl übersprungener Treffer. Haben mehrere Treffer dieselben Werte in sort, ist ihre Reihenfolge nicht festgelegt, und sie können zwischen zwei Seiten doppelt kommen oder fehlen; id als letztes Attribut in sort oder ein Abgleich mit Überlappung (Delta-Sync) hilft dagegen.
0 <= value <= 10000000sort?|array<string>Attribute, nach denen sortiert wird; nur sortierbare Attribute (sortable in x-bimetrics-filter). Ein Attribut mit sortable: false ergibt 400.
upper?unknownObergrenze für range, einschließlich.
value?unknownVergleichswert: für eq ein Wert oder null, für in ein Text, für oneof eine Liste.
Filterattribute
Dokumentiert sind diese Attribute für attribute; für sort nur die als sortierbar markierten. Aufbau des Filters: Filtern und Paginieren.
| 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. |
Eine Seite der Treffer.
application/json- response
Eine Seite gefundener Kontakte.
items?array<>|Die Treffer dieser Seite.
limit?|Verwendetes limit.
offset?integerVerwendetes offset.
total?integerAnzahl aller Treffer des Filters.
curl --fail-with-body "https://app.bimetrics.de/api/contact/filter" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"direction":["asc","asc"],"limit":100,"offset":0,"sort":["companyName","id"]}'{ "items": [ { "addresses": [ { "city": "Hamburg", "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "country": "DE", "createdAt": "2026-03-18T10:02:51Z", "id": "181e7601-21c2-47fa-bffa-008d1113c6d8", "postalCode": "20457", "street": "Am Sandtorkai 12", "updatedAt": "2026-03-18T10:02:51Z" } ], "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "companyName": "Brauhaus Elbwiese GmbH", "contactInfo": { "contactPersonName": "Erika Mustermann", "email": "buchhaltung@brauhaus-elbwiese.de" }, "createdAt": "2026-03-18T10:02:51Z", "customerKind": "business", "customerNumber": 1004, "deletedAt": null, "id": "b17e8812-eae4-49b6-b5dc-30510635cb07", "paymentInfo": { "bic": "BYLADEM1001", "iban": "DE02120300000000202051", "vatId": "DE987654321" }, "type": "customer", "updatedAt": "2026-09-01T09:13:02Z", "vatCheck": { "checkedAt": "2026-03-18T10:02:53Z", "valid": true, "vatId": "DE987654321" } }, { "addresses": [ { "city": "Kiel", "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "country": "DE", "createdAt": "2026-08-28T06:15:21Z", "id": "4b6951dc-e603-4bf5-9135-ef5a7d9a417c", "postalCode": "24103", "street": "Bahnhofstraße 8", "updatedAt": "2026-08-28T06:15:21Z" } ], "companyId": "9c388e1f-04a6-4770-80bd-66cd98dd00d5", "companyName": "Papierhaus Wendt KG", "contactInfo": {}, "createdAt": "2026-08-28T06:15:21Z", "customerNumber": 1007, "deletedAt": null, "id": "fd493c80-9d79-4bb1-aab5-09992633dce0", "paymentInfo": { "iban": "DE02500105170137075030", "vatId": "DE246813579" }, "type": "supplier", "updatedAt": "2026-08-28T06:15:21Z" } ], "limit": 100, "offset": 0, "total": 2}Kontaktangaben prüfen POST
Prüft IBAN, USt-IdNr. sowie PLZ und Ort wie beim Anlegen und Ändern eines Kontakts, ohne etwas zu speichern und ohne einen anderen Dienst zu fragen. `ibanValid` sagt, ob das Speichern die IBAN annimmt. `hints` sind dieselben Hinweise wie in der Antwort von createContact und updateContact. Ob eine USt-IdNr. aus dem EU-Ausland vergeben ist, prüft bimetrics weiter beim Speichern über VIES. Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.
Kontakt lesen GET
Liefert einen Kontakt mit Anschriften, Kontakt- und Zahlungsdaten. Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.