Zum Hauptinhalt springen
LiveStand 19. November 2026

SwissRETS JSON über die Supply API

Deine Software sendet jedes Inserat als SwissRETS JSON per HTTP PUT. Homematch prüft es gegen das Schema und veröffentlicht es.

Das Profil

SwissRETS ist der offene Schweizer Standard für Inseratsdaten, herausgegeben von Qualipool. Unser Profil homematch-swissrets-json-2 legt fest, wie die Daten über HTTP kommen: SwissRETS 3.6.0 als Inhalt, was SwissRETS nicht kennt in extensions.

Ein Inserat senden

Ein PUT pro Inserat, mit deiner eigenen Inseratsnummer als Schlüssel. Ein neuer PUT ersetzt das Inserat, und publicationState bestimmt, ob es sichtbar ist.

HTTP
PUT https://api-tenant.homematch.ch/api/marketplace/supply/v1/listings/{providerListingKey}

Header

X-Api-Key
Dein Zugangsschlüssel. Jede Agentur hat ihren eigenen.
Idempotency-Key
Eindeutig pro Sendung. Eine Wiederholung mit demselben Schlüssel wird nur einmal angewendet.
X-Provider-Contract
Die Vertragsversion, für die du gebaut hast, heute 2.

Inhalt

profileVersion
Immer homematch-swissrets-json-2.
swissRetsVersion
Immer 3.6.0.
revision
Deine Kennung für diesen Stand des Inserats.
revisionOrdinal
Eine Zahl, die mit jeder Änderung steigt. Ein älterer Stand ersetzt keinen neueren.
occurredAt
Wann du das Inserat geändert hast (ISO 8601).
publicationState
published oder unpublished.
property
Ein Objekt aus SwissRETS properties[], unverändert.
extensions.parties
Wer die Anfragen erhält: genau ein inquiry_recipient mit E-Mail.
extensions.declaredActions
Was Interessierte tun können: heute eine Aktion mit kind «inquiry».

Was ein Inserat braucht

  • Eine Postleitzahl
  • Einen Preis oder «Preis auf Anfrage»
  • Einen Titel oder eine Beschreibung
  • Mindestens ein Bild
  • Wohnfläche (areaBwf, sonst areaNwf) und Zimmer grösser als 0, oder weggelassen
  • Genau einen Empfänger für Anfragen

Was wir lesen

Diese Felder aus SwissRETS properties[] fliessen ins Inserat. Andere Felder überspringen wir, auch die Anhänge logos und landRegisterExtracts.

  • id
  • referenceId
  • visualReferenceId
  • type
  • availability
  • categories
  • address
  • prices
  • characteristics
  • localizations
  • seller
  • bfs
  • externalReference
  • minergieCertification

Den ganzen Bestand senden

Statt einzeln kannst du deinen ganzen Bestand auf einmal senden: PUT complete-inventory ersetzt alle Inserate deines Zugangs, und was fehlt, wird zurückgezogen.

Fehler

Jede Ablehnung ist ein RFC-9457-Problem mit festem code. Ungültige Werte kommen als validation_failed (400) mit JSON-Pointern. Ein Inserat, das nicht veröffentlicht werden kann, wird mit supply_listing_unpublishable (422) abgelehnt, und ein schon veröffentlichtes bleibt auf seinem letzten Stand.

Beispiel

listing.json
{
  "profileVersion": "homematch-swissrets-json-2",
  "swissRetsVersion": "3.6.0",
  "revision": "rev-2026-11-19-001",
  "revisionOrdinal": 1001,
  "occurredAt": "2026-11-19T09:00:00Z",
  "publicationState": "published",
  "property": {
    "id": "example-rent-1234",
    "referenceId": "R-1234",
    "visualReferenceId": "1234.01.0012",
    "type": "rent",
    "categories": [
      "apartment"
    ],
    "availability": {
      "state": "active",
      "start": "2027-01-01T00:00:00+01:00"
    },
    "address": {
      "street": "Musterstrasse",
      "streetNumber": "12",
      "postalCode": "8000",
      "locality": "Zürich",
      "countryCode": "CH"
    },
    "prices": {
      "currency": "CHF",
      "rent": {
        "net": 2150,
        "extra": 250,
        "gross": 2400,
        "interval": "month",
        "referring": "all"
      }
    },
    "characteristics": {
      "numberOfRooms": 3.5,
      "areaBwf": 82,
      "floor": 2,
      "hasBalcony": "applies",
      "hasElevator": "applies"
    },
    "localizations": [
      {
        "languageCode": "de",
        "title": "Helle 3½-Zimmer-Wohnung mit Balkon",
        "description": "Ruhige Lage, fünf Minuten zum Bahnhof.",
        "attachments": {
          "images": [
            {
              "url": "https://media.example.invalid/1234/living-room.jpg",
              "mimeType": "image/jpeg"
            }
          ]
        }
      }
    ],
    "seller": {
      "organization": {
        "id": "agency-42",
        "legalName": "Beispiel Immobilien AG",
        "email": "info@example.invalid"
      },
      "contactPerson": {
        "givenName": "Lea",
        "familyName": "Beispiel",
        "email": "lea.beispiel@example.invalid"
      }
    }
  },
  "extensions": {
    "parties": [
      {
        "providerPartyId": "agency-42-inquiries",
        "role": "inquiry_recipient",
        "kind": "organization",
        "profile": {
          "email": "vermietung@example.invalid"
        }
      }
    ],
    "declaredActions": [
      {
        "kind": "inquiry"
      }
    ]
  }
}

Bereit zum Testen?

Wir geben dir Zugang zu unserer Testumgebung und prüfen deine Anbindung, bevor sie live geht.