# Credits in der API (https://webmetic.de/docs/api/credits)

Nur zwei Endpunkte kosten Credits: `POST /contacts/reveal` und `POST /contacts/find`. Zum Beispiel suchen Sie über `/contacts/search` die Vertriebsleitung eines Getränkeherstellers, der Ihre Preisseite besucht hat. Diese Suche ist kostenlos. Erst das Freischalten der E-Mail-Adresse kostet Credits.

Credits kaufen Sie im Dashboard, nicht über die API. Woher Ihre Credits kommen und wo Sie die Rechnung finden, steht unter [Credits](https://webmetic.de/docs/credits).

## Vom Aufruf zur Abbuchung [#vom-aufruf-zur-abbuchung]

1. **Freischalten anfragen**: Sie rufen `/contacts/reveal` oder `/contacts/find` auf und wählen E-Mail, Telefon oder beides.
2. **Credits prüfen**: Webmetic prüft, ob Ihre Credits für alle angefragten Datenarten reichen. Wenn sie nicht reichen, antwortet die API mit Status `402`.
3. **Daten liefern**: Webmetic sucht die Kontaktdaten und liefert, was es findet.
4. **Credits abbuchen**: Webmetic bucht nur für die Datenarten ab, die es geliefert hat.

## Kostenpflichtige und kostenlose Endpunkte [#kostenpflichtige-und-kostenlose-endpunkte]

Diese Endpunkte kosten Credits:

- **`POST /contacts/reveal`**: schaltet E-Mail oder Telefon einer Person aus Ihrer Suche frei. Die Datenart wählen Sie mit `reveal_email` und `reveal_phone`.
- **`POST /contacts/find`**: sucht eine passende Person und schaltet ihre Daten im selben Aufruf frei. Sie wählen mit `reveal` zwischen `email`, `phone` und `both`. Ohne Angabe schaltet der Aufruf die E-Mail frei.

Alle anderen Endpunkte kosten keine Credits: `/contacts/search`, `/contacts/lookup`, `/contacts/credits`, die Endpunkte von Visitor Intelligence und die Webhooks. Enrichment kostet derzeit keine Credits. Mehr dazu unter [Enrichment](https://webmetic.de/docs/enrichment).

Anfragen mit dem [Demo-Schlüssel](https://webmetic.de/docs/api/schnellstart#ohne-konto-testen) `wmtc_demo` kosten nie Credits, auch nicht an `/contacts/reveal` und `/contacts/find`.

Suche und Freischalten funktionieren erst, wenn Ihr Konto die [Ansprechpartner eingerichtet](https://webmetic.de/docs/ansprechpartner/einrichten) hat. Bis dahin antwortet die API mit `CONTACTS_SETUP_REQUIRED`.

Dieselben Regeln gelten im KI-Assistenten und in n8n, Make und Zapier, weil diese Anbindungen dieselben Endpunkte nutzen.

## Regeln für die Abbuchung [#regeln-für-die-abbuchung]

Webmetic rechnet je Datenart ab, und E-Mail (mit dem LinkedIn-Profil, wenn eines vorliegt) und Telefon sind zwei getrennte Arten:

- **Nur Geliefertes**: Wenn Webmetic eine Datenart nicht findet, kostet diese Datenart nichts, auch wenn die Suche sie als vorhanden markiert hat.
- **Kein Treffer**: Wenn `/contacts/find` keine passende Person findet, antwortet die API mit `found: false` und bucht nichts ab.
- **Erneutes Abrufen**: Daten, die Ihr Konto schon freigeschaltet hat, kosten für alle Benutzer und Schlüssel Ihres Kontos nichts mehr. Die Antwort enthält dann `from_cache: true`.
- **Neue Datenart**: Wenn Sie zur E-Mail später das Telefon anfragen, zahlen Sie nur das Telefon.
- **Nie doppelt**: Webmetic bucht wiederholte oder gleichzeitige Anfragen für dieselben Daten nur einmal ab.
- **Alles oder nichts**: Wenn Sie E-Mail und Telefon in einem Aufruf anfragen, bucht Webmetic beide zusammen ab oder gar nicht.
- **Fehler**: Wenn ein Aufruf mit einem Fehler endet, bucht Webmetic nichts ab.

Ein anderes Webmetic-Konto zahlt für dieselben Daten selbst. Ein Freischalten lässt sich nicht rückgängig machen, und die API gibt keinen Verlauf der verbrauchten Credits aus.

## Credits in den Antworten [#credits-in-den-antworten]

Jede Antwort von `/contacts/search`, `/contacts/reveal` und `/contacts/find` enthält zwei Felder zu Ihren Credits:

- **`credits_used`**: wie viele Credits dieser Aufruf abgebucht hat.
- **`credits_remaining`**: wie viele Credits Ihr Konto nach dem Aufruf noch hat.

Deshalb brauchen Sie nach jeder Aktion keinen eigenen Abruf der Credits.

## Credits-Endpunkt [#credits-endpunkt]

`GET /contacts/credits` zeigt, wie viele Credits Ihr Konto hat und was jede Aktion kostet. Der Abruf ist kostenlos und funktioniert auch ohne eingerichtete Ansprechpartner.

```bash tab="cURL" tab-group="lang"
curl "https://hub.webmetic.de/contacts/credits" \
  -H "Authorization: wmtc_IHR_API_SCHLUESSEL"
```

```js tab="JavaScript" tab-group="lang"
const res = await fetch('https://hub.webmetic.de/contacts/credits', {
  headers: { Authorization: 'wmtc_IHR_API_SCHLUESSEL' },
});
const credits = await res.json();
```

```python tab="Python" tab-group="lang"
import requests

res = requests.get(
    "https://hub.webmetic.de/contacts/credits",
    headers={"Authorization": "wmtc_IHR_API_SCHLUESSEL"},
)
credits = res.json()
```

| Feld | Typ | Bedeutung |
| --- | --- | --- |
| `balance` | Ganzzahl | Wie viele Credits Ihr Konto hat. Ein Konto ohne Credits erhält `0`, keinen Fehler |
| `costs` | Objekt | Kosten je Aktion in Credits |
| `costs.search` | Ganzzahl | Suche nach Ansprechpartnern |
| `costs.email` | Ganzzahl | Freischalten der E-Mail |
| `costs.phone` | Ganzzahl | Freischalten des Telefons |
| `costs.email_phone` | Ganzzahl | Freischalten von E-Mail und Telefon zusammen |

Lesen Sie die Kosten aus `costs`, statt sie fest in Ihren Code zu schreiben. Die Werte sind dieselben, die das Dashboard beim Freischalten zeigt.

## Zu wenig Credits [#zu-wenig-credits]

Wenn Ihre Credits nicht reichen, antwortet die API mit Status `402` und bucht nichts ab, denn Webmetic prüft das, bevor es Daten abruft.

Die API antwortet deshalb auch dann mit `402`, wenn Webmetic die Daten gar nicht gefunden hätte. Wie bei allen Fehlern der API steht der Fehler im Feld `detail`:

| Feld | Bedeutung |
| --- | --- |
| `detail.error` | `INSUFFICIENT_CREDITS` |
| `detail.message` | Lesbarer Text zum Fehler |
| `detail.required` | Wie viele Credits die Aktion braucht |
| `detail.available` | Wie viele Credits Ihr Konto hat |

Kaufen Sie in diesem Fall im Dashboard Credits nach und wiederholen Sie danach den Aufruf. Die API kann keine Credits kaufen und lädt Ihre Credits auch nicht automatisch auf. Alle Fehlercodes stehen unter [Fehler](https://webmetic.de/docs/api/fehler).

## Nächste Schritte [#nächste-schritte]

- [Credits kaufen](https://webmetic.de/docs/credits#kauf-und-rechnung): Credits im Dashboard aufladen und die Rechnung finden.
- [Fehler](https://webmetic.de/docs/api/fehler): Alle Statuscodes und Fehlercodes der API nachschlagen.
- [Credits abfragen](https://webmetic.de/docs/api/referenz/contacts/credits): Den Endpunkt `/contacts/credits` in der Referenz ausprobieren.