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