bimetricsEntwickler
Kontakte

Kontakt lesen

Als Markdown ansehen

Benötigte Berechtigung:contacts:read(Kontakte lesen)

GET
/api/contact/{id}

Liefert einen Kontakt mit Anschriften, Kontakt- und Zahlungsdaten.

Benötigt einen Schlüssel mit der Berechtigung contacts:read oder read.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

Pfadparameter

id*string

ID des Kontakts (UUID).

Formatuuid

Antworten

Erfolg.

application/json
  1. response

Ein Kontakt: Kunde, Lieferant oder Partner.

addresses?array<>

Anschriften.

companyId?string

ID der Firma.

Formatuuid
companyName?string

Name.

contactInfo?

Kontaktdaten.

createdAt?string

Anlage in bimetrics.

Formatdate-time
customerKind?string

Steuerlich: business Unternehmen, private Privatperson. Fehlt, wenn unbekannt.

Wert in"business""private"
customerNumber?integer

Kunden- bzw. Lieferantennummer; ergibt Debitor- und Kreditorkonto.

datevAccounts?

Personenkonten des Kontakts im DATEV-Export, aus der Kundennummer abgeleitet wie die Buchungen; nur lesbar. In der Antwort von getContact, createContact und updateContact und je Treffer von filterContacts, nur wenn die Firma einen Kontenrahmen hat.

defaultCostCenterId?string

Kostenstelle oder Verteilung, die neue Belege dieses Kontakts bekommen, solange sie noch keine haben. Fehlt ohne.

Formatuuid
deletedAt?|

Gilt als gelöscht seit diesem Zeitpunkt; null, solange nicht gelöscht. Gelöschte Einträge liefern nur die Suchrouten mit includeDeleted.

Formatdate-time
externalRef?string

Externe Kunden- oder Lieferantenreferenz, in der App „Alte Nummer“, etwa die Kundennummer aus dem früheren Programm. Steht nie auf Belegen.

hints?array<>

Hinweise zu Angaben des gespeicherten Kontakts, die nie sperren, etwa eine USt-IdNr. mit falscher Prüfziffer oder ein Ort, der nicht zur PLZ gehört. Nur in der Antwort von createContact und updateContact und nur, wenn es welche gibt.

id?string

ID des Kontakts.

Formatuuid
noReminders?boolean

Nicht mahnen: Keine Rechnung an diesen Kontakt lässt sich mahnen, auch ausgestellte. Fehlt, wenn aus.

paymentInfo?

Zahlungsdaten.

paymentTerms?

Eigenes Zahlungsziel und Skonto des Kunden. Fehlt, wenn er die Vorgaben der Firma nutzt.

source?string

Zugang bei Anlage: web, api oder mcp.

type?string

Art des Kontakts.

Wert in"customer""supplier""partner"
updatedAt?string

Letzte Änderung.

Formatdate-time
vatCheck?

Letzte Prüfung der USt-IdNr. über VIES. Fehlt ohne Prüfung.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/contact/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Authorization: Bearer $BIMETRICS_API_KEY"
Beispielantwort
{  "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"  }}

Kontakte suchen POST

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`.

Kontakt ändern PUT

Ändert nur übergebene Felder; ausgelassene Unterfelder bleiben erhalten. expectedUpdatedAt muss dem gelesenen Kontakt entsprechen. Es gelten die Regeln des Kontaktformulars der App, wie über MCP: Bankverbindung, steuerliche Art, USt-IdNr., Land, Name und Anschrift lassen sich auch bei bereits verwendeten Kontakten ändern, die Kundennummer nur, solange der Kontakt in keinem Beleg steht (`409 CustomerNumberInUse`). Eine neue IBAN ohne die Länge ihres Landes oder mit falscher Prüfziffer lehnt die API mit `400 InvalidIban` ab; eine gespeicherte bleibt, leeren geht immer. Hinweise, die nie sperren, stehen in `hints`. Benötigt einen Schlüssel mit der Berechtigung `contacts:write`.