Dieser Guide zeigt, wie du deiner Website einen WBS-Eignungsschätzer hinzufügst — ein kleines Formular, in dem ein Haushalt seine Größe, sein Bundesland und sein Nettoeinkommen eingibt und eine unverbindliche Eignungsschätzung erhält. Der Check ist zustandslos: Es wird nichts gespeichert, also kann er sicher direkt aus dem Browser laufen.

Welches Problem das löst: Wohnungssuchende möchten vorab wissen, ob sie voraussichtlich für einen WBS in Frage kommen, bevor sie sich bewerben. Das Einbetten des Checks reduziert nicht qualifizierte Bewerbungen.

Beta / dark-shipped. Der WBS-Check (Plan 60) ist hinter dem Feature-Flag WBS_API_ENABLED gegated; solange es aus ist, liefert er 404. Er ist GA-ready und möglicherweise der erste Plan-60-Endpoint, der für deine Organisation aktiviert wird — kläre das mit deinem WOHNO-Ansprechpartner. Die Operation ist x-internal und noch nicht in der öffentlichen Referenz.

Voraussetzungen

Ein Publishable Key (pk_live_…) mit einer Origin-Allowlist — wbs:check ist auf der Publishable-Whitelist, das ist also im Browser sicher.
Der Scope wbs:check.
WBS_API_ENABLED für deine Organisation aktiviert.

Schritt 1 — Den Check aufrufen

Es ist ein einzelnes zustandsloses POST. Der Body ist strikt:

curl -X POST https://wohno.de/api/v1/wbs/check \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "bundesland": "BE",
    "household_size": 3,
    "monthly_net_income": 2800
  }'

bundesland — der zweistellige deutsche Bundesland-Code nach ISO-3166-2 (z. B. BE, BY).
household_size — 1 bis 12.
monthly_net_income — Haushalts-Nettoeinkommen in EUR.
city_override — optional, für Städte mit eigenen Einkommensgrenzen.

Antwort (200):

{
  "data": {
    "eligible": true,
    "income_limit": 3400,
    "headroom": 600,
    "basis": "Unverbindliche Schätzung auf Basis der Landeseinkommensgrenzen. Keine Rechtsverbindlichkeit."
  }
}

basis trägt den rechtlich erforderlichen "unverbindliche Schätzung"-Hinweis — zeige ihn immer neben dem Ergebnis an.

Schritt 2 — Ein minimales Formular verdrahten

<form id="wbs-form">
  <select name="bundesland" required>
    <option value="BE">Berlin</option>
    <option value="BY">Bayern</option>
    <!-- … all 16 states … -->
  </select>
  <input name="household_size" type="number" min="1" max="12" required />
  <input name="monthly_net_income" type="number" min="0" required />
  <button type="submit">Check eligibility</button>
</form>
<p id="wbs-result"></p>
 
<script>
  const WOHNO_PK = "pk_live_xxxxxxxxxxxxxxxxxxxxxxxx";
 
  document.getElementById("wbs-form").addEventListener("submit", async (e) => {
    e.preventDefault();
    const f = new FormData(e.target);
    const res = await fetch("https://wohno.de/api/v1/wbs/check", {
      method: "POST",
      headers: { "X-API-Key": WOHNO_PK, "Content-Type": "application/json" },
      body: JSON.stringify({
        bundesland: f.get("bundesland"),
        household_size: Number(f.get("household_size")),
        monthly_net_income: Number(f.get("monthly_net_income")),
      }),
    });
 
    const out = document.getElementById("wbs-result");
    if (!res.ok) {
      const { error } = await res.json();
      out.textContent = `Could not check (${error.code}).`;
      return;
    }
    const { data } = await res.json();
    out.textContent = data.eligible
      ? `Likely eligible — about ${data.headroom} € below the limit. ${data.basis}`
      : `Likely not eligible. ${data.basis}`;
  });
</script>

Der Browser fügt den Origin-Header hinzu; er wird gegen die Allowlist deines Keys validiert.

Fehlerbehandlung

Code	HTTP	Was passiert ist	Lösung
`VALIDATION_ERROR`	400	Unbekannter Bundesland-Code oder unbekanntes Feld	Gültiges ISO-2-`bundesland` senden; strikter Body.
`ORIGIN_NOT_ALLOWED`	403	Aufrufende Domain nicht auf der Allowlist	Domain unter Einstellungen → API hinzufügen.
`ORIGIN_REQUIRED`	403	`pk_`-Key ohne `Origin` aufgerufen	Aus einem Browser aufrufen.
`NOT_FOUND`	404	`WBS_API_ENABLED` ist aus	Aktivierung des Flags anfragen.
`RATE_LIMITED`	429	Über 60 Requests / 60 s für diesen Scope	Eingaben entprellen; `Retry-After` respektieren.

Siehe die Konventions-Referenz.

Best Practices

Zeige den Hinweis. Die Schätzung ist unverbindlich; rendere immer basis.
Entprellen (Debounce). Dieser Scope ist auf 60 Requests pro 60 Sekunden rate-limitiert — rufe nicht bei jedem Tastendruck auf.
Keine Persistenz nötig. Der Check speichert nichts; alle Ergebnisse, die du behalten willst, gehören dir.

Nächste Schritte

Inserate auf deiner Website einbetten — den Check mit einem wbs_only-gefilterten Inserats-Grid kombinieren.
Einen Discovery-Aggregator bauen — der andere Publishable-Plan-60-Endpoint.
API-Referenz — WBS-Eingabe- und Ergebnisfelder.

Voraussetzungen#

Schritt 1 — Den Check aufrufen#

Schritt 2 — Ein minimales Formular verdrahten#

Fehlerbehandlung#

Best Practices#