# REST API: listings in the OpenImmo 2.0 shape

Adresse: https://docs.athaus.ai/en/api/v1/inserate

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

Type: Reference
Last updated: 2026-11-17

A listing at `/v1/listings` has the shape of [OpenImmo 2.0](https://www.openimmo.de), 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:

| Part          | Content                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------- |
| `data`        | the property: type, location, prices, spaces, conditions, energy, features, texts, management |
| `metadata`    | where the listing comes from: your ids under `source`                                         |
| `contact`     | the person responsible for the listing ([The contact person](#contact))                       |
| `media`       | the photos and documents, named by `externalMediaId` ([Photos and documents](#media))         |
| `userDefined` | the 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 [#two-ids]

| Id                  | Whose | Where                                                                            |
| ------------------- | ----- | -------------------------------------------------------------------------------- |
| `externalListingId` | yours | in the path of every call; it is `metadata.source.offererMarketingKey`           |
| `listingId`         | ours  | in 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](#several-flats)). 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 [#several-flats]

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 [#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.

```bash
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" } }
  }'
```

```json
{
  "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](#status)).

## Read a listing [#read-a-listing]

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

The listing sits under `listing`:

```json
{
  "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](/en/api/v1/blaettern)).

## Status [#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](/en/api/v1/hinausgehen)). `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](/en/api/v1/projekte#unit-status). `projectId` in the listing shows that it is a unit.

## Drafts [#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.

```bash
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 [#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](/en/api/v1/schreiben#bedingt-schreiben)).

```bash
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 [#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:

| Type            | Meaning                                            |
| --------------- | -------------------------------------------------- |
| `FIELD_IGNORED` | a member was accepted but Athaus does not store it |

## Data the standard has no member for [#user-defined]

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

| Name                         | Type    | Content                                            |
| ---------------------------- | ------- | -------------------------------------------------- |
| `location.district`          | string  | the district or quarter                            |
| `tenure`                     | string  | freehold, leasehold, commonhold or cooperative     |
| `price.deposit`              | decimal | the rent deposit                                   |
| `price.associationFee`       | decimal | the monthly fee to the owners' association         |
| `conditions.interiorQuality` | string  | `BASIC`, `STANDARD`, `UPSCALE` or `LUXURY`         |
| `conditions.interiorQuality` | string  | `BASIC`, `STANDARD`, `UPSCALE` or `LUXURY`         |
| `management.petsPolicy`      | string  | `ALLOWED`, `NOT_ALLOWED` or `CASE_BY_CASE`         |
| `management.usage`           | string  | free text on the use                               |
| `structure.parkingSpaces`    | integer | the number of parking spaces when no type is known |

Five more names start with `de.` and belong to the German profile ([Country profiles](/en/api/v1/laenderprofile)).

## Photos and documents [#media]

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:

| Parameter         | Meaning                                                                                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`            | `photo`, `floor_plan` or `document`. Without it an image is a `photo` and a PDF a `document`. A `photo` must be an image.                                                                                                             |
| `documentType`    | for 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` |
| `fileName`        | the name the file carries in the app and in downloads                                                                                                                                                                                 |
| `externalMediaId` | your 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`).                            |

```bash
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.

```json
"media": [
  { "externalMediaId": "front", "title": "Street side" },
  { "externalMediaId": "plan-ground-floor" },
  { "externalMediaId": "energy-certificate" }
]
```

| You send                                    | Effect                                                                                                                                                                   |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| no `media`                                  | the files stay as they are                                                                                                                                               |
| a list                                      | named 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](/en/api/v1#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]

`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 [#members]

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 [#ListingPatch]

| Member        | Type              | Required | Note |
| ------------- | ----------------- | -------- | ---- |
| `data`        | `object \| any`   | no       |      |
| `metadata`    | `object \| any`   | no       |      |
| `userDefined` | `object[] \| any` | no       |      |
| `media`       | `object[] \| any` | no       |      |
| `contact`     | `object \| any`   | no       |      |

### ListingEnergy [#ListingEnergy]

| Member                                                               | Type            | Required | Note                                                                                                                                                                                                        |
| -------------------------------------------------------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `energyType`                                                         | `object`        | no       |                                                                                                                                                                                                             |
| `energyType.heatMethod`                                              | `string`        | no       | One of `CENTRAL`, `INDIVIDUAL`, `STOREY`.                                                                                                                                                                   |
| `energyType.heatForm`                                                | `object`        | no       |                                                                                                                                                                                                             |
| `energyType.heatForm.air`                                            | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.heatForm.radiator`                                       | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.heatForm.stove`                                          | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.heatForm.underfloor`                                     | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.heatForm.wallCeiling`                                    | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource`                                            | `object`        | no       |                                                                                                                                                                                                             |
| `energyType.energySource.coal`                                       | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.districtHeating`                            | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.electric`                                   | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.gas`                                        | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.geothermal`                                 | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.liquidGas`                                  | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.oil`                                        | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.solarHeat`                                  | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.solarPower`                                 | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.wind`                                       | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.wood`                                       | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energySource.woodPellet`                                 | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energyGeneration`                                        | `object`        | no       |                                                                                                                                                                                                             |
| `energyType.energyGeneration.fossilburning`                          | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energyGeneration.heatpump`                               | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.energyGeneration.combinedHeatAndPowerPlant`              | `boolean`       | no       |                                                                                                                                                                                                             |
| `energyType.maxElectricalPower`                                      | `integer`       | no       | -9007199254740991 to 9007199254740991.                                                                                                                                                                      |
| `countrySpecific`                                                    | `object`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de`                                                 | `object`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates`                              | `object[]`      | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].nameOfCertificate`          | `string`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].certificateType`            | `string`        | no       | One of `ENEV2008`, `ENEV2014`, `ENEV2026`, `NOT_AVAILABLE`, `NOT_NECESSARY`, `AT_VISIT`.                                                                                                                    |
| `countrySpecific.de.energyCertificates[].certificateBasedOn`         | `string`        | no       | One of `NEED`, `CONSUMPTION`.                                                                                                                                                                               |
| `countrySpecific.de.energyCertificates[].isResidentialBuilding`      | `boolean`       | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].primaryEnergySource`        | `string`        | no       | One of `NO_INFORMATION`, `SOLAR`, `WIND`, `COAL`, `GAS`, `OIL`, `WOOD`, `DISTRICT_HEATING`, `ELECTRICITY`.                                                                                                  |
| `countrySpecific.de.energyCertificates[].efficiencyClass`            | `string`        | no       | One of `A_PLUS`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`.                                                                                                                                                    |
| `countrySpecific.de.energyCertificates[].releaseDate`                | `string (date)` | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].validUntil`                 | `string (date)` | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].yearOfConstructionBuilding` | `integer`       | no       | -9007199254740991 to 9007199254740991.                                                                                                                                                                      |
| `countrySpecific.de.energyCertificates[].yearOfConstructionHeating`  | `integer`       | no       | -9007199254740991 to 9007199254740991.                                                                                                                                                                      |
| `countrySpecific.de.energyCertificates[].overallEnergyNeed`          | `number`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].primaryEnergyNeed`          | `number`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].electricityNeed`            | `number`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].heatingNeed`                | `number`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].overallEnergyConsumption`   | `number`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].primaryEnergyConsumption`   | `number`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].isWaterHeatingIncluded`     | `boolean`       | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].electricityConsumption`     | `number`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].heatingConsumption`         | `number`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.energyCertificates[].energyConsumptionIndicator` | `number`        | no       |                                                                                                                                                                                                             |
| `countrySpecific.de.houseEnergyStandardType`                         | `string`        | no       | One 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.primaryEnergySource`                             | `string`        | no       |                                                                                                                                                                                                             |

### Projects [#projects]

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

### ProjectEventObject [#ProjectEventObject]

| Member              | Type     | Required | Note              |
| ------------------- | -------- | -------- | ----------------- |
| `object`            | `string` | yes      | Always `project`. |
| `id`                | `string` | yes      | The `projectId`.  |
| `externalProjectId` | `string` | yes      |                   |
| `projectId`         | `string` | yes      |                   |

### ProjectDeleted [#ProjectDeleted]

| Member    | Type      | Required | Note              |
| --------- | --------- | -------- | ----------------- |
| `object`  | `string`  | yes      | Always `project`. |
| `id`      | `string`  | yes      |                   |
| `deleted` | `boolean` | yes      | Always `true`.    |
