bimetricsEntwickler
Kontakte

Kontakt anlegen

Als Markdown ansehen

Benötigte Berechtigung:contacts:write(Kontakte anlegen und ändern)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
post/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.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

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

Header-Parameter

Idempotency-Key*string

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

Muster^[!-~]+$
Länge1 <= length <= 128

Request-Body

application/json
  1. body

Kontakt anlegen oder gezielt ändern; ausgelassene Felder bleiben bei Änderungen erhalten.

addresses?array<>

Vollständige Liste der gewünschten Anschriften.

companyName?string

Name oder Firma des Kontakts.

contactInfo?

Gezielte Änderungen an Kontakt- und Kommunikationsdaten.

customerKind?string

Steuerlich: business (Unternehmen) oder private (Privatperson). Nur beim Ändern, beim Anlegen 400 InvalidContactWrite.

Wert in"business""private"
customerNumber?integer

Kundennummer. Ändern lässt sie sich nur, solange der Kontakt in keinem Beleg steht, sonst 409 CustomerNumberInUse.

defaultCostCenterId?string

Kostenstelle oder Verteilung für neue Belege des Kontakts als ID, ein leerer String entfernt sie. Eine archivierte wird abgelehnt. Ohne Angabe bleibt sie.

expectedUpdatedAt?string

Exakter zuletzt gelesener updatedAt-Wert einschließlich Sekundenbruchteilen; für Änderungen erforderlich.

Formatdate-time
externalRef?string

Stabile externe Kundenreferenz, höchstens 255 Zeichen.

forceDuplicate?boolean

Nur nach bewusster Prüfung einer Namensdublette verwenden; umgeht keine USt-IdNr.- oder externalRef-Dublette.

noReminders?boolean

Nicht 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?string

Kontaktart customer, supplier oder partner.

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/" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{}'
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,  "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`.