# USt-IdNr. und IBAN mit den Belegen abgleichen (https://developer.bimetrics.de/reference/contacts/get-contact-numbers)

`GET https://app.bimetrics.de/api/contact/{id}/numbers`

operationId: `getContactNumbers` · Berechtigung (Scope): `contacts:read` · Bereich: Kontakte

Meldet, wenn eine andere USt-IdNr. oder IBAN auf mehr Belegen des Kontakts steht als seine eigene. So fallen Kontakte auf, die früher die Nummer einer anderen Firma übernommen haben, weil ein Beleg nur wegen eines ähnlichen Namens bei ihnen gelandet ist. Solange die Nummer beim Kontakt gespeichert ist, landen weiterhin Belege dieser Firma bei ihm. Die App zeigt das als Frage unter dem Feld. Ausgewertet werden die letzten 500 ausgelesenen Belege des Kontakts. Bei Eingangsbelegen ist er der Aussteller, bei Rechnungen der Empfänger. Die Nummer des Kontakts gilt als gefunden, wenn sie im Belegtext steht, auch wenn sie dort mit Leerzeichen, Punkten oder Bindestrichen geschrieben ist. Eine fremde USt-IdNr. erkennt bimetrics im Belegtext nur, wenn sie aus Deutschland, Österreich oder der Schweiz stammt. Als fremde IBAN gilt die IBAN, die bimetrics aus dem Beleg ausgelesen hat, sofern sie auch im Belegtext steht. Nummern der eigenen Firma zählen nicht. `documentIds` nennt die Belege mit der Nummer des Kontakts, `otherDocumentIds` die mit `other`, jeweils höchstens die 50 neuesten. `vatId` und `iban` sind `null`, wenn der Kontakt keine gültige Nummer hat, wenn keine andere Nummer auf mehr Belegen steht als seine eigene oder wenn jemand die Nummer mit `POST /api/contact/{id}/numbers/confirm` bestätigt hat. Gehört die Nummer nicht zum Kontakt, lässt sie sich mit `PUT /api/contact/{id}` entfernen. Die Belege der anderen Firma verschiebt `POST /api/document/bulk/counterparty` zum richtigen Kontakt.

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

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `id` | path | ja | string (uuid) | ID des Kontakts (UUID). |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/contact/{id}/numbers" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY"
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: ContactNumbers |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diese Route (`APIKeyPermissionDenied`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 404 | Nicht gefunden (`NotFound`). | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200 (`ContactNumbers`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `iban` | NumberDoubt | Abgleich der IBAN oder `null`. |
| `vatId` | NumberDoubt | Abgleich der USt-IdNr. oder `null`. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json