Skip to main content
LiveAs of November 19, 2026

SwissRETS JSON through the Supply API

Your software sends each listing as SwissRETS JSON via HTTP PUT. Homematch validates it against the schema and publishes it.

The profile

SwissRETS is the open Swiss standard for listing data, published by Qualipool. Our profile homematch-swissrets-json-2 defines how the data arrives over HTTP: SwissRETS 3.6.0 as the content, and anything SwissRETS doesn’t cover in extensions.

Send a listing

One PUT per listing, with your own listing number as the key. A new PUT replaces the listing, and publicationState decides whether it’s visible.

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

Headers

X-Api-Key
Your access key. Each agency has its own.
Idempotency-Key
Unique per submission. A retry with the same key is applied only once.
X-Provider-Contract
The contract version you built for, currently 2.

Body

profileVersion
Always homematch-swissrets-json-2.
swissRetsVersion
Always 3.6.0.
revision
Your identifier for this version of the listing.
revisionOrdinal
A number that increases with every change. An older version never replaces a newer one.
occurredAt
When you changed the listing (ISO 8601).
publicationState
published or unpublished.
property
One object from SwissRETS properties[], unchanged.
extensions.parties
Who receives the inquiries: exactly one inquiry_recipient with an email.
extensions.declaredActions
What interested people can do: currently one action with kind “inquiry”.

What a listing needs

  • A postcode
  • A price or “price on request”
  • A title or a description
  • At least one image
  • Living area (areaBwf, otherwise areaNwf) and rooms greater than 0, or left out
  • Exactly one recipient for inquiries

What we read

These fields from SwissRETS properties[] go into the listing. We skip other fields, including the logos and landRegisterExtracts attachments.

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

Send your whole inventory

Instead of one at a time, you can send your whole inventory at once: PUT complete-inventory replaces all listings under your access, and anything missing is withdrawn.

Errors

Every rejection is an RFC 9457 problem with a fixed code. Invalid values come back as validation_failed (400) with JSON Pointers. A listing that can’t be published is rejected with supply_listing_unpublishable (422), and one that’s already published stays at its last version.

Example

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"
      }
    ]
  }
}

Ready to test?

We’ll give you access to our test environment and check your integration before it goes live.