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.
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
{
"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.