> ## Documentation Index
> Fetch the complete documentation index at: https://api.housera.ro/llms.txt
> Use this file to discover all available pages before exploring further.

# The fields of a listing

> What you send for an apartment, a house, a land, or a commercial space.

A listing is a flat JSON object: each piece of information is a top-level field (`price`, `rooms`, `floor`), and the amenities are a list of codes (`features`). You send the same fields to `POST /listings/validate`, `POST /listings`, `PATCH /listings/{code}`, and `PUT /listings/ref/{ref}`.

This page explains the groups of fields and provides a complete example for the most used types. The complete list, with the type and unit of each field and with the property types for which they exist, is in [vocabular](/en/vocabulary), at `GET /schema`.

## Identity

<ParamField body="type" type="string" required>
  Property type: `apartment`, `house`, `room`, `complex`, `land`, `commercial`, `warehouse`, `garage`, `hospitality`, `special`.
</ParamField>

<ParamField body="subtype" type="string">
  Subtype, from the vocabulary of the type (e.g., `studio`, `standard`, `penthouse` for apartment; `building`, `agricultural` for land). Mandatory for all types that have subtypes, meaning all except `room` and `complex`.
</ParamField>

<ParamField body="transaction" type="string" required>
  `sale` (sale), `rent` (rental) or `short_stay` (hotel regime). Not every type accepts every transaction: valid pairs are in `types[].transactions` of the vocabulary. The hotel regime can only be used when the vocabulary marks it `available: true`.
</ParamField>

The type and the transaction do not change after creation.

## Text

<ParamField body="title" type="string" required>
  Title, between 10 and 90 characters, with real content (not "aaaaaaaaaa").
</ParamField>

<ParamField body="description" type="string" required>
  Description, between 30 and 5,000 characters. Do not include phone numbers, emails, or website addresses in the text: contact goes through the listing page, and moderation rejects listings with contact details in the text.
</ParamField>

<ParamField body="content_locale" type="string">
  Language of the title and description, as ISO 639-1 code (`ro`, `en`). If missing, Housera deduces it from the text.
</ParamField>

## Location

`latitude`, `longitude`, `city`, and `street` are mandatory for any listing. Optionally, send `county`, `area` (neighborhood), `street_number`, and `landmark` (a nearby landmark). Details are in [location guide](/en/guides/location).

## Price

<ParamField body="price" type="integer" required>
  Whole amount, in the currency from `price_currency`. The meaning follows the transaction: total price for sale, monthly rent for rental, price per night in hotel regime. It is always the price of the entire offer, never per square meter. Mandatory, except for developments (`complex`), where the “from” price is calculated from the types of units.
</ParamField>

<ParamField body="price_currency" type="string" default="EUR">
  Currency's ISO 4217 code. Accepted currencies are in `currencies` of the vocabulary (`EUR`, `RON`, `USD`, and others). All amounts of the listing (deposit, additional costs) are in the same currency.
</ParamField>

<ParamField body="negotiable" type="boolean">
  The price is negotiable.
</ParamField>

In the response, `price` is the value in euros, which the search compares, with `currency: "EUR"`. The amount and the currency you sent are in `price_declared`:

```json theme={null}
{ "price": 502, "currency": "EUR", "price_period": "month", "price_declared": { "amount": 2500, "currency": "RON" } }
```

The value in euros follows the daily reference rate.

## Areas

All areas are in m², with at most two decimals.

| Field | What it measures | Mandatory for |
| - | - | - |
| `usable_area_sqm` | Usable area. | all types, except `land`, `house`, and `complex` |
| `built_area_sqm` | Built area. | `house` |
| `land_area_sqm` | Land area. | `land`, `house` |

The vocabulary also contains secondary areas (balconies, terrace, yard, offices, production, storage), each for the types to which it makes sense.

## Specifications

Fields that describe the property: rooms, floor, year, condition, heating, energy certificate, and many others. The mandatory ones depend on the type:

| Field | What it is | Mandatory for |
| - | - | - |
| `rooms`, `bedrooms`, `bathrooms` | Number of rooms, bedrooms, bathrooms. `bedrooms` and `bathrooms` can be `0`. | `apartment`, `house` |
| `floor` | Floor, as a level code: `ground`, `floor_1` … `floor_99`, `semi_basement`, `basement`, `mezzanine`, `attic`, `roof_space`. | `apartment`, `room` |
| `total_floors` | Number of floors of the building (`0` = ground floor only). | `apartment`, `house` |
| `partitioning` | Layout: `detached`, `semi_detached`, `undetached`, `circular`, `railroad`, `unknown`. | `apartment`, except for studios and one-bedroom apartments |
| `attic` | Attic or loft: `attic`, `roof_space`, `none`. | `house` |
| `flood_risk` | Flood risk statement, `true` or `false`. | `land`, `house` |

A few useful rules:

* **Codes, not labels.** Send `"condition": "renovated"`, not `"Renovat"`. Codes and their labels (in Romanian and English) are in the vocabulary.
* **The floor as a number is accepted**: `3` is read as `floor_3`, `0` as `ground`, `-1` as `semi_basement`. In responses, you always receive the code.
* **Booleans** are `true` or `false`.
* **Lists** (`heating_types`, `orientations`, `materials`) are lists of codes, even with a single element.
* **Withdrawn codes remain valid:** if you send an old code, it is read as its successor (see `retired` in the vocabulary).

## Amenities

`features` is a list of codes from the amenities catalog, for example `["ac", "elevator", "intercom"]`. The catalog has several hundred codes, grouped (utilities, security, exterior, building…), each with the property types to which it applies. You can find it in `features` of the vocabulary.

An amenity that is not in the catalog or does not apply to the type of the listing does not block the submission: it is ignored and appears in `warnings[]`.

## Contact

The name and email of contact are those of the account that holds the key. The phone is the one from the account, unless you send another one:

<ParamField body="contact_phone" type="string">
  A valid phone number. It is saved in international format (E.164). Mandatory only if there is no phone in the account.
</ParamField>

## What does not exist for type and transaction

Each field exists only for certain combinations of type and transaction: the deposit (`deposit_months`) only for rentals, the number of loading gates (`dock_doors_count`) only for warehouses, layout only for apartments. A field submitted where it does not exist **is not an error**: it is ignored, and the response signals it to you in `warnings[]`:

```json theme={null}
"warnings": [
  { "pointer": "/deposit_months", "code": "not_for_transaction" },
  { "pointer": "/partitioning", "code": "not_for_type" }
]
```

Thus, you can send the same fields from the CRM for all listings, and Housera keeps only what makes sense. It is still worth cleaning your mapping until `warnings[]` is empty.

## Complete examples

All the examples below pass validation as they are.

<Tabs>
  <Tab title="Apartment">
    ```json theme={null}
    {
      "type": "apartment",
      "subtype": "standard",
      "transaction": "sale",
      "title": "Apartament 3 camere decomandat, Copou, Iași",
      "description": "Apartament luminos cu trei camere decomandate, renovat în 2022, la cinci minute de Parcul Copou. Bucătărie închisă, centrală proprie pe gaz, ferestre noi și boxă la subsol.",
      "city": "Iași",
      "county": "Iași",
      "area": "Copou",
      "street": "Strada Vasile Lupu",
      "street_number": "12",
      "latitude": 47.1752,
      "longitude": 27.5701,
      "price": 98000,
      "price_currency": "EUR",
      "negotiable": true,
      "rooms": 3,
      "bedrooms": 2,
      "bathrooms": 1,
      "floor": "floor_2",
      "total_floors": 4,
      "usable_area_sqm": 65.5,
      "built_area_sqm": 72,
      "partitioning": "detached",
      "year_built": 1985,
      "condition": "renovated",
      "heating_types": ["gas"],
      "energy_certificate": "b",
      "features": ["ac", "elevator", "intercom"]
    }
    ```
  </Tab>

  <Tab title="House">
    ```json theme={null}
    {
      "type": "house",
      "subtype": "detached",
      "transaction": "sale",
      "title": "Casă individuală 4 camere cu curte, Bucium, Iași",
      "description": "Casă individuală pe parter și etaj, construită în 2018, cu patru camere, două băi și curte amenajată de 320 mp. Acces asfaltat, toate utilitățile, garaj și loc de parcare în curte.",
      "city": "Iași",
      "area": "Bucium",
      "street": "Strada Plopii fără Soț",
      "street_number": "7A",
      "latitude": 47.1238,
      "longitude": 27.6211,
      "price": 185000,
      "price_currency": "EUR",
      "rooms": 4,
      "bedrooms": 3,
      "bathrooms": 2,
      "total_floors": 1,
      "built_area_sqm": 140,
      "usable_area_sqm": 118,
      "land_area_sqm": 320,
      "attic": "none",
      "flood_risk": false,
      "year_built": 2018,
      "condition": "good",
      "heating_types": ["gas"],
      "features": ["garden", "fenced", "parking_open", "alarm"]
    }
    ```
  </Tab>

  <Tab title="Land">
    ```json theme={null}
    {
      "type": "land",
      "subtype": "building",
      "transaction": "sale",
      "title": "Teren intravilan 800 mp, deschidere 20 m, Miroslava",
      "description": "Teren intravilan plan, cu deschidere de 20 m la drum asfaltat, curent și apă la limita proprietății. PUZ aprobat pentru locuințe individuale, potrivit pentru o casă cu grădină.",
      "city": "Miroslava",
      "county": "Iași",
      "street": "Strada Principală",
      "latitude": 47.1486,
      "longitude": 27.5032,
      "price": 52000,
      "price_currency": "EUR",
      "land_area_sqm": 800,
      "flood_risk": false,
      "land_classification": "inside_built_up_area",
      "land_frontage": 20,
      "pot": 35,
      "cut": 0.9,
      "features": ["utility_electricity", "utility_water_mains", "utility_road", "zoning_plan_approved"]
    }
    ```
  </Tab>

  <Tab title="Commercial space">
    ```json theme={null}
    {
      "type": "commercial",
      "subtype": "offices",
      "transaction": "rent",
      "title": "Spațiu de birouri 120 mp, open space, Piața Victoriei, București",
      "description": "Spațiu de birouri de 120 mp într-o clădire de clasă A, cu open space, două săli de ședințe și recepție. Acces 24/7, parcare subterană în clădire, la trei minute de metrou.",
      "city": "București",
      "county": "București",
      "area": "Piața Victoriei",
      "street": "Bulevardul Lascăr Catargiu",
      "street_number": "40",
      "latitude": 44.4517,
      "longitude": 26.0893,
      "price": 2400,
      "price_currency": "EUR",
      "deposit_months": 2,
      "usable_area_sqm": 120,
      "floor": "floor_3",
      "commercial_class": "a",
      "commercial_layout": "open_space",
      "features": ["ac", "access_24_7", "structured_cabling", "reception_area"]
    }
    ```
  </Tab>
</Tabs>

## Residential developments

A development (`complex`) does not have a single floor, area, or price. Instead, you send the list of unit types in `unit_types`. At least one row must be complete: `label`, `area_sqm`, `units_count`, and `price_from`.

```json theme={null}
"unit_types": [
  { "label": "2 camere", "rooms": 2, "area_sqm": 54, "area_sqm_to": 60, "units_count": 48, "price_from": 72000 },
  { "label": "3 camere", "rooms": 3, "area_sqm": 78, "units_count": 32, "price_from": 99000 }
]
```

The displayed price of the development is the lowest `price_from`. Project fields (status, delivery term, height regime) are in the vocabulary, in fields that have `complex` among types.

## Media links

<ParamField body="media_links" type="object">
  External links, `http` or `https`, of up to 500 characters: `video` (a presentation video), `tour` (a virtual tour), `plan` (a plan).
</ParamField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.