AthausDocs

REST API: listings in the OpenImmo 2.0 shape

Read and write listings in the shape of OpenImmo 2.0. Two ids, drafts, receipts, warnings, and every member of a listing.

Last updated:

A listing at /v1/listings has the shape of OpenImmo 2.0, the open standard for real estate data. The names, the nesting and the allowed values are the standard's. This page describes how Athaus uses it, in our own words. The standard itself defines what each member means.

A listing is an object with these parts:

PartContent
datathe property: type, location, prices, spaces, conditions, energy, features, texts, management
metadatawhere the listing comes from: your ids under source
contactthe person responsible for the listing (The contact person)
mediathe photos and documents, named by externalMediaId (Photos and documents)
userDefinedthe extension slot of the standard, for data it has no member for

On reading, contact is there only when the listing has a person of its own, media only when it has files, and userDefined only when it has entries. Athaus adds four members to a listing it returns: listingId, status, createdAt and updatedAt. A client that only knows the standard ignores them.

OpenImmo is also how listings travel elsewhere. Athaus sends OpenImmo XML 1.2.7 to portals and reads any 1.2.x version from a connected CRM. Sending OpenImmo 2.0 JSON exists in the code, but no portal accepts it today. All of them use the same listing; this page is about the REST API.

The JSON shape of /v1 follows OpenImmo 2.0.0. Version 1.2.7 is an XML transfer format with German element names and has no JSON or REST form. XML 1.2.7 stays supported for import and for the portals.

Two ids

IdWhoseWhere
externalListingIdyoursin the path of every call; it is metadata.source.offererMarketingKey
listingIdoursin responses, and in inquiries, viewings and files as the listing they belong to

On create and on PUT, both members of metadata.source are required: offererMarketingKey and offererEstateId. Athaus stores only offererMarketingKey. offererEstateId is not stored and comes back in responses with the same value as the key. Send the same value in both. The key is your reference and must be unique in the office (reference_already_exists). An address, together with its unit, belongs to one listing per office (address_already_exists, see several flats in one house). An id is 1 to 128 letters, digits, dots, underscores or hyphens, and does not start or end with a dot; anything else is a 400.

Several flats in one house

A house with several flats is several listings at one address. Tell them apart with data.location.unit (the flat or unit number), staircase and entrance. Athaus holds one listing per office for each combination of street, house number, postal code, city, unit, staircase and entrance. Case and extra spaces do not count: WE 3b and we 3B are the same unit.

  • Without unit, staircase and entrance, the address alone is the key, as before: a second listing at the same address is 409 address_already_exists. This protects against doubles when an integration retries without its key.
  • The 409 names the listing of your own office that holds the address and unit, with its externalListingId and listingId. There are two ways out: change that listing, or send a unit that tells the two apart.
  • A PATCH that moves a listing onto a taken unit is the same 409. Clearing unit, staircase or entrance of a running listing is 409 listing_active, like clearing any address part. A comma inside one of the three is stored as a space.
  • A draft that only knows a postal code and a city has no street, so it holds no address: any number of such drafts can exist. The address is checked when a street is added.
  • The OpenImmo XML for portals carries the unit in wohnungsnr (with staircase and entrance appended, for the exact address only). New-build projects with their units are not part of this.

Create a listing

Creating a listing answers 202 with a receipt. The listing is written before the answer, so you can read it at once.

curl -X POST "https://api.athaus.ai/v1/listings" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "estateType": "APARTMENT",
      "estateSubType": { "apartment": "MULTI_STOREY" },
      "distributionType": "BUY",
      "location": {
        "postalcode": "10435",
        "city": "Berlin",
        "street": "Kastanienallee",
        "houseNumber": "12",
        "country": "DEU",
        "geometry": { "type": "Point", "coordinates": [13.4128, 52.5395] }
      },
      "prices": { "currency": "EUR", "buy": { "price": { "amount": 350000 } } },
      "spaces": { "spaceMeasureUnit": "SQUARE_METER", "residential": { "livingSpace": 62 } },
      "structure": { "rooms": { "numberOfRooms": 2 } },
      "texts": { "headline": { "en": "Bright two-room apartment" } }
    },
    "metadata": { "source": { "offererEstateId": "WE-12", "offererMarketingKey": "WE-12" } }
  }'
{
  "requestId": "req_0f3a9c2b7d4e41a8b6c15e9d3a7f2b04",
  "listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
  "externalListingId": "WE-12",
  "warnings": []
}

The header Location points to the new listing. A coordinate is required in data.location.geometry as a GeoJSON point: longitude first, then latitude. Creating does not publish. A new listing is a draft until it is published (Status).

Read a listing

curl "https://api.athaus.ai/v1/listings/WE-12" \
  -H "Authorization: Bearer ath_live_..."

The listing sits under listing:

{
  "listing": {
    "listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
    "status": "draft",
    "createdAt": "2026-11-11T09:30:00Z",
    "updatedAt": "2026-11-11T09:30:00Z",
    "data": {
      "estateType": "APARTMENT",
      "estateSubType": { "apartment": "MULTI_STOREY" },
      "distributionType": "BUY",
      "location": {
        "postalcode": "10435",
        "city": "Berlin",
        "street": "Kastanienallee",
        "houseNumber": "12",
        "country": "DEU",
        "geometry": { "type": "Point", "coordinates": [13.4128, 52.5395] }
      },
      "prices": { "currency": "EUR", "buy": { "price": { "amount": 350000 } } },
      "spaces": { "spaceMeasureUnit": "SQUARE_METER", "residential": { "livingSpace": 62 } },
      "structure": { "rooms": { "numberOfRooms": 2 } },
      "texts": { "headline": { "en": "Bright two-room apartment" } }
    },
    "metadata": { "source": { "offererEstateId": "WE-12", "offererMarketingKey": "WE-12" } }
  }
}

With If-None-Match and the current ETag the call answers 304 without a body. GET /v1/listings lists the ids page by page (Pagination).

Status

status is one of draft, active, paused, reserved and closed. closed means sold or let. Which one it is stands in data.management.marketStatus. reserved and closed show there too. status is read-only: you do not set it with PATCH, and Athaus does not store data.management.marketStatus from a body (FIELD_IGNORED). These calls change the state:

  • POST /v1/listings/{externalListingId}/publish puts the listing online. The checks are those of the button in the app: the plan, the mandatory details, the energy certificate, a photo. If the key has the scope approve and the office's automation for publishing is set to "Automatic", the call answers 200 with the listing, and status is active. Otherwise it answers 202 with a proposal that a person confirms in the app (What leaves the office). Idempotency-Key is required. A listing that is not complete is 409 listing_incomplete, and errors names what is missing.
  • POST /v1/listings/{externalListingId}/unpublish takes a running listing off the market at once and answers 200, and status is paused. Taking down only removes, so it waits for nobody. A listing that is not running is 409 listing_not_online.
  • POST /v1/listings/{externalListingId}/unit-status sets the status of a listing that is a unit of a new-build project and answers 200 with the listing. It is described with the projects. projectId in the listing shows that it is a unit.

Drafts

An address is often not known yet when a listing is first entered. With draft=true on POST and PUT, only metadata.source, data.distributionType and data.estateType are required, and everything else is checked when the listing is published. OpenImmo has no draft parameter and no publish operation, so draft is an addition of Athaus.

curl -X POST "https://api.athaus.ai/v1/listings?draft=true" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "data": { "estateType": "APARTMENT", "distributionType": "BUY" }, "metadata": { "source": { "offererEstateId": "WE-15", "offererMarketingKey": "WE-15" } } }'

Change and delete

  • PUT /v1/listings/{externalListingId} needs a complete body (or draft=true) and then changes the listing like PATCH: what the body does not name stays, null clears it. For an unknown id PUT answers 404. With createIfMissing=true Athaus creates the listing instead, so a sender can always PUT.
  • PATCH /v1/listings/{externalListingId} changes parts as a merge patch (RFC 7396): a member you send replaces the stored one, null removes it, a list is replaced whole. The result must still be a valid listing. OpenImmo has no PATCH; this is an addition.
  • DELETE /v1/listings/{externalListingId} removes the listing and answers 202. A published listing, a running brokerage agreement and upcoming viewings stop it (409).

All three accept If-Match and answer 412 when the state changed (Writing).

curl -X PATCH "https://api.athaus.ai/v1/listings/WE-12" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Content-Type: application/merge-patch+json" \
  -d '{ "data": { "prices": { "buy": { "price": { "amount": 340000 } } } } }'

Warnings

A write that worked can still carry notes. They stand in warnings of the receipt, each with a type and a message. There is one type:

TypeMeaning
FIELD_IGNOREDa member was accepted but Athaus does not store it

Data the standard has no member for

userDefined is the extension slot of the standard. Athaus writes these names into it and reads them back:

NameTypeContent
location.districtstringthe district or quarter
tenurestringfreehold, leasehold, commonhold or cooperative
price.depositdecimalthe rent deposit
price.associationFeedecimalthe monthly fee to the owners' association
conditions.interiorQualitystringBASIC, STANDARD, UPSCALE or LUXURY
conditions.interiorQualitystringBASIC, STANDARD, UPSCALE or LUXURY
management.petsPolicystringALLOWED, NOT_ALLOWED or CASE_BY_CASE
management.usagestringfree text on the use
structure.parkingSpacesintegerthe number of parking spaces when no type is known

Five more names start with de. and belong to the German profile (Country profiles).

Photos and documents

You upload a file once and then name it in the listing. The two steps do not depend on each other: you can upload files before the listing exists.

1. Upload. POST /v1/medias takes the file itself as the body, not JSON. Content-Type is its type: image/jpeg, image/png, image/webp or application/pdf, at most 25 MB. Athaus checks that the bytes are of that type; a PDF sent as image/png is a 415. The query says what the file is:

ParameterMeaning
kindphoto, floor_plan or document. Without it an image is a photo and a PDF a document. A photo must be an image.
documentTypefor a document, which paper it is: energy_certificate, floor_plan, living_area, land_registry, declaration_of_division, budget_plan, logs, utilities, lease, property_tax, expose, modernization or other
fileNamethe name the file carries in the app and in downloads
externalMediaIdyour id for the file, which the listing names in media. Without it Athaus uses the id of the answer. It is unique in the office while the file waits for a listing (409 reference_already_exists).
curl -X POST "https://api.athaus.ai/v1/medias?externalMediaId=front&fileName=front.jpg" \
  -H "Authorization: Bearer $ATHAUS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: image/jpeg" \
  --data-binary @front.jpg

The answer is 201 with id, externalMediaId, kind, documentType, fileName, mimeType, sizeBytes and, for images, width and height. The id stays the id of the file under /v1/files. With Idempotency-Key a retry is safe: the same bytes and parameters return the same answer and store no second file. Athaus removes a file that no listing names within seven days. At most 200 files and 1 GB wait for a listing in an office (413 payload_too_large).

2. Name. media in the listing is a list of externalMediaId with a title. The order of the list is the order of the files within each kind. The first photo is the cover.

"media": [
  { "externalMediaId": "front", "title": "Street side" },
  { "externalMediaId": "plan-ground-floor" },
  { "externalMediaId": "energy-certificate" }
]
You sendEffect
no mediathe files stay as they are
a listnamed uploads become files of the listing, named files of the listing get their order and title, and files that came through the API and are no longer named are removed
media: [] or media: null (with PATCH)every file that came through the API is removed

Files someone added in the app have no externalMediaId. A list never removes them. You can order and title them by naming their id as externalMediaId. If you upload a file under the id of a file the listing already has and name it in media, it replaces that file. The replacement carries the id of the upload, and the old address under /v1/files stops working.

An id that is neither an upload nor a file of the listing, appears twice, or belongs to another office is a 400 with the entry media[n].externalMediaId. A listing takes at most 40 files and 500 MB (413 payload_too_large). On an error nothing is created.

3. Read. The listing returns media when it has files: per file externalMediaId, title, id, kind, documentType, fileName, mimeType, sizeBytes, width, height and contentUrl. You fetch the contentUrl (/v1/files/{id}/content) with the same key (Downloading files). The order is photos, floor plans, documents, each by rank.

Athaus does not fetch a file from an address you name. The bytes always come from you.

The contact person

contact names the person who appears in the exposé and in the portal export. Athaus stores the name (firstName and lastName, or name, which is split at the last space), emailAddress and phoneNumber. A listing without contact keeps the responsible person of the office, and the answer has no contact. As soon as one of the four members is set, it replaces the responsible person as a whole: what is missing does not appear in the exposé.

As elsewhere, a member that is missing stays, a named null clears it, and contact: null removes the person. Every other member of contact (salutation, mobile number, address, displayedInformation and so on) is not stored. Each one you send appears in a FIELD_IGNORED warning.

The members of a listing

This is every member Athaus accepts and returns. Types that are lists of values are at the end. The standard says what each member means.

ListingPatch

MemberTypeRequiredNote
dataobject | anyno
metadataobject | anyno
userDefinedobject[] | anyno
mediaobject[] | anyno
contactobject | anyno

ListingEnergy

MemberTypeRequiredNote
energyTypeobjectno
energyType.heatMethodstringnoOne of CENTRAL, INDIVIDUAL, STOREY.
energyType.heatFormobjectno
energyType.heatForm.airbooleanno
energyType.heatForm.radiatorbooleanno
energyType.heatForm.stovebooleanno
energyType.heatForm.underfloorbooleanno
energyType.heatForm.wallCeilingbooleanno
energyType.energySourceobjectno
energyType.energySource.coalbooleanno
energyType.energySource.districtHeatingbooleanno
energyType.energySource.electricbooleanno
energyType.energySource.gasbooleanno
energyType.energySource.geothermalbooleanno
energyType.energySource.liquidGasbooleanno
energyType.energySource.oilbooleanno
energyType.energySource.solarHeatbooleanno
energyType.energySource.solarPowerbooleanno
energyType.energySource.windbooleanno
energyType.energySource.woodbooleanno
energyType.energySource.woodPelletbooleanno
energyType.energyGenerationobjectno
energyType.energyGeneration.fossilburningbooleanno
energyType.energyGeneration.heatpumpbooleanno
energyType.energyGeneration.combinedHeatAndPowerPlantbooleanno
energyType.maxElectricalPowerintegerno-9007199254740991 to 9007199254740991.
countrySpecificobjectno
countrySpecific.deobjectno
countrySpecific.de.energyCertificatesobject[]no
countrySpecific.de.energyCertificates[].nameOfCertificatestringno
countrySpecific.de.energyCertificates[].certificateTypestringnoOne of ENEV2008, ENEV2014, ENEV2026, NOT_AVAILABLE, NOT_NECESSARY, AT_VISIT.
countrySpecific.de.energyCertificates[].certificateBasedOnstringnoOne of NEED, CONSUMPTION.
countrySpecific.de.energyCertificates[].isResidentialBuildingbooleanno
countrySpecific.de.energyCertificates[].primaryEnergySourcestringnoOne of NO_INFORMATION, SOLAR, WIND, COAL, GAS, OIL, WOOD, DISTRICT_HEATING, ELECTRICITY.
countrySpecific.de.energyCertificates[].efficiencyClassstringnoOne of A_PLUS, A, B, C, D, E, F, G, H.
countrySpecific.de.energyCertificates[].releaseDatestring (date)no
countrySpecific.de.energyCertificates[].validUntilstring (date)no
countrySpecific.de.energyCertificates[].yearOfConstructionBuildingintegerno-9007199254740991 to 9007199254740991.
countrySpecific.de.energyCertificates[].yearOfConstructionHeatingintegerno-9007199254740991 to 9007199254740991.
countrySpecific.de.energyCertificates[].overallEnergyNeednumberno
countrySpecific.de.energyCertificates[].primaryEnergyNeednumberno
countrySpecific.de.energyCertificates[].electricityNeednumberno
countrySpecific.de.energyCertificates[].heatingNeednumberno
countrySpecific.de.energyCertificates[].overallEnergyConsumptionnumberno
countrySpecific.de.energyCertificates[].primaryEnergyConsumptionnumberno
countrySpecific.de.energyCertificates[].isWaterHeatingIncludedbooleanno
countrySpecific.de.energyCertificates[].electricityConsumptionnumberno
countrySpecific.de.energyCertificates[].heatingConsumptionnumberno
countrySpecific.de.energyCertificates[].energyConsumptionIndicatornumberno
countrySpecific.de.houseEnergyStandardTypestringnoOne of UNSPECIFIED, LOW_ENERGY_40, LOW_ENERGY_60, PASSIVE_HOUSE, ENERGY_EFFICIENT_40, ENERGY_EFFICIENT_55, ENERGY_EFFICIENT_70, LOW_ENERGY_HOUSE, NULL_ENERGY_HOUSE, PLUS_ENERGY_HOUSE.
countrySpecific.de.primaryEnergySourcestringno

Projects

A project has these members; the units of a project are listings.

ProjectEventObject

MemberTypeRequiredNote
objectstringyesAlways project.
idstringyesThe projectId.
externalProjectIdstringyes
projectIdstringyes

ProjectDeleted

MemberTypeRequiredNote
objectstringyesAlways project.
idstringyes
deletedbooleanyesAlways true.

Keep reading

On this page