Kontakt anlegen
Benötigte Berechtigung:contacts:write(Kontakte anlegen und ändern)
Echte Wirkung
/api/contact/Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.
Legt einen Kontakt ohne Bankverbindung und steuerliche Art an; beides lässt sich danach mit updateContact ergänzen. Eine E-Mail-Adresse, die der Versand nicht nehmen würde, lehnt die API mit 400 InvalidContactEmail ab. Gleiche normalisierte USt-IdNr., externalRef oder gleicher Name ohne Rechtsform ergeben 409 ContactDuplicate mit existingId. Nur eine Namensdublette kann mit forceDuplicate bestätigt werden.
Benötigt einen Schlüssel mit der Berechtigung contacts:write.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
Idempotency-Key*stringStabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt.
^[!-~]+$1 <= length <= 128application/json- body
Kontakt anlegen oder gezielt ändern; ausgelassene Felder bleiben bei Änderungen erhalten.
addresses?array<>Vollständige Liste der gewünschten Anschriften.
companyName?stringName oder Firma des Kontakts.
contactInfo?Gezielte Änderungen an Kontakt- und Kommunikationsdaten.
customerKind?stringSteuerlich: business (Unternehmen) oder private (Privatperson). Nur beim Ändern, beim Anlegen 400 InvalidContactWrite.
"business""private"customerNumber?integerKundennummer. Ändern lässt sie sich nur, solange der Kontakt in keinem Beleg steht, sonst 409 CustomerNumberInUse.
defaultCostCenterId?stringKostenstelle oder Verteilung für neue Belege des Kontakts als ID, ein leerer String entfernt sie. Eine archivierte wird abgelehnt. Ohne Angabe bleibt sie.
expectedUpdatedAt?stringExakter zuletzt gelesener updatedAt-Wert einschließlich Sekundenbruchteilen; für Änderungen erforderlich.
date-timeexternalRef?stringStabile externe Kundenreferenz, höchstens 255 Zeichen.
forceDuplicate?booleanNur nach bewusster Prüfung einer Namensdublette verwenden; umgeht keine USt-IdNr.- oder externalRef-Dublette.
noReminders?booleanNicht mahnen: Keine Rechnung an diesen Kontakt lässt sich mahnen, auch ausgestellte; false hebt es auf. Ohne Angabe bleibt der Wert.
paymentInfo?Steuer-, Bank-, Leitweg- und Lieferantenkennung; Bankdaten nur beim Ändern.
paymentTerms?Zahlungsziel und Skonto des Kunden für neue Rechnungen. Ersetzt beide: Ein ausgelassener Wert nimmt wieder den der Firma, {} leert beide. Ohne Angabe bleiben sie. Regeln verletzt: 400 BadRequest mit context.field, etwa paymentTerms.cashDiscount.days.
type?stringKontaktart customer, supplier oder partner.
Erfolg.
application/json- response
Ein Kontakt: Kunde, Lieferant oder Partner.
addresses?array<>Anschriften.
companyId?stringID der Firma.
uuidcompanyName?stringName.
contactInfo?Kontaktdaten.
createdAt?stringAnlage in bimetrics.
date-timecustomerKind?stringSteuerlich: business Unternehmen, private Privatperson. Fehlt, wenn unbekannt.
"business""private"customerNumber?integerKunden- 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?stringKostenstelle oder Verteilung, die neue Belege dieses Kontakts bekommen, solange sie noch keine haben. Fehlt ohne.
uuiddeletedAt?|Gilt als gelöscht seit diesem Zeitpunkt; null, solange nicht gelöscht. Gelöschte Einträge liefern nur die Suchrouten mit includeDeleted.
date-timeexternalRef?stringExterne 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?stringID des Kontakts.
uuidnoReminders?booleanNicht 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?stringZugang bei Anlage: web, api oder mcp.
type?stringArt des Kontakts.
"customer""supplier""partner"updatedAt?stringLetzte Änderung.
date-timevatCheck?Letzte Prüfung der USt-IdNr. über VIES. Fehlt ohne Prüfung.
curl --fail-with-body "https://app.bimetrics.de/api/contact/" \ -H "Authorization: Bearer $BIMETRICS_API_KEY" \ -H "Idempotency-Key: rechnung-2026-001" \ -H "Content-Type: application/json" \ -d '{}'{ "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, "externalRef": "customer-1042", "id": "b17e8812-eae4-49b6-b5dc-30510635cb07", "paymentInfo": { "vatId": "DE987654321" }, "source": "api", "type": "customer", "updatedAt": "2026-09-01T09:13:02Z", "vatCheck": { "checkedAt": "2026-03-18T10:02:53Z", "valid": true, "vatId": "DE987654321" }}Straßenvorschläge beim Tippen GET
Schlägt für Deutschland bis zu 8 Straßen vor, deren Name so beginnt wie `q`, mit Ort und Postleitzahlen. Das sind dieselben Daten wie die Vorschläge im Feld „Straße und Hausnummer“ des Kontaktformulars der App. Gesucht wird erst ab drei Buchstaben, darunter bleibt `streets` leer. Schreibweise wie beim Ort: Groß- und Kleinschreibung und Satzzeichen zählen nicht, „ue“ gilt als „ü“, „Str.“ und „Straße“ gelten gleich. Eine Hausnummer am Ende stört nicht. Mit `city` grenzt du ein: Meint der Name genau einen Ort, kommen nur dessen Straßen, sonst die aller Orte, die so beginnen („Frankfurt“ trifft Frankfurt am Main und Frankfurt (Oder)). Mit `postalCode` kommen nur Straßen, die diese Postleitzahl haben. Reihenfolge: ein genau getippter Name vor längeren, dann Straßen in größeren Orten zuerst. Ohne `city` sortiert `near` (eine Postleitzahl, in der App die der eigenen Firma) die Straßen aus der Nähe nach vorn: zuerst nach gleichen führenden Ziffern, dann nach dem Abstand der Leitregionen, erst dann nach der Ortsgröße. Die Liste ist nicht vollständig, OpenStreetMap kennt nicht jede Straße, und Hausnummern fehlen ganz. Eine Straße ohne Vorschlag ist deshalb kein Fehler. Für andere Länder kommt `supported: false`. Ohne `q` antwortet die Route mit `400` und `context.field` = `q`. Quelle: OpenStreetMap (ODbL 1.0). Zeigst du die Vorschläge an, nenne `attribution` mit Link auf https://www.openstreetmap.org/copyright. Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.
Kontaktangaben prüfen POST
Prüft IBAN, USt-IdNr., PLZ und Ort sowie die E-Mail 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`.