# Ähnliche Kontakte lesen (https://developer.bimetrics.de/reference/contacts/get-similar-contacts)

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

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

Liefert bis zu fünf andere Kontakte, die nach denselben Regeln wie bei der Zuordnung neuer Belege dieselbe Firma sein könnten, den ähnlichsten zuerst. Die App zeigt sie im Kontakt als Hinweis „Es gibt einen ähnlichen Kontakt“. Eine andere USt-IdNr. oder eine andere Rechtsform auf beiden Seiten schließt einen Kontakt aus, eine andere Postleitzahl oder eine Rechtsform nur auf einer Seite nicht. Gehören zwei Kontakte zur selben Firma, verschiebt `POST /api/contact/{id}/merge` die Belege des Kontakts `{id}` zum Kontakt `targetContactId`. Die App verschiebt dabei vom Kontakt mit weniger Belegen (`documentCount`) zum Kontakt mit mehr.

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}/similar" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY"
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: Array<SimilarContact> |
| 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

Array aus `SimilarContact`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `companyName` | string | Name des Kontakts. |
| `customerNumber` | integer | Kontaktnummer. |
| `documentCount` | integer | Anzahl der Belege des Kontakts. |
| `id` | string (uuid) | ID des Kontakts. |
| `type` | string | Kontakttyp: `customer`, `supplier` oder `partner`. |

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