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

# Publish a development

> For property developers: a residential development with its unit types, number of floors and delivery date.

A residential development (`type: complex`) is a single listing for a whole project: the buildings or houses, the unit types in them, the starting price and the delivery date. Each apartment, house, commercial space or parking spot on sale is a listing of its own, linked to the development.

## Who publishes a development

Developments are published by property developers whose company Housera has approved, and by agencies that hold a confirmed exclusive marketing mandate on the project. A developer can create the development through the API too, with an ordinary key from its account at [Settings → API](https://housera.ro/setari/api). An agency creates the development in the portal, under "Add listing": it names the developer and uploads the mandate contract. Once the mandate is confirmed, the agency can edit the development through the API as well. See [The marketing mandate](https://api.housera.ro/en/guides/complex.md#the-marketing-mandate).

| Situation | Response |
| - | - |
| An agency creates a development through the API (`POST /listings`, or `PUT /listings/ref/{ref}` with a new ID) | `422`, `complex_developers_only` on `/type` |
| An agency edits its development while the mandate is confirmed or the request is still waiting for a decision | `200` or `202`, as for any edit |
| An agency edits its development after the mandate was revoked or expired | `404`: the development left the site (`hidden`) and can no longer be edited, like any hidden listing |
| An agency edits its development after the mandate was refused | `422`, `complex_developers_only` on `/type` |
| The developer has taken the development over | `404` on the agency's keys |
| The account belongs to an individual | `422`, `complex_developers_only` on `/type` |
| The account belongs to a company that is not approved yet | `422`, `firm_not_approved` on `/contact_as` (for any listing, not just developments) |

An agency without a mandate does not publish the development. It publishes the units as ordinary listings and links them to the development once the development's company approves it as a partner. See [Partner agencies](https://api.housera.ro/en/guides/partners.md).

## What you send

A development has the fields every listing has: `type`, `transaction`, `title`, `description` and the location (`latitude`, `longitude`, `city`, `street`; see [Location](https://api.housera.ro/en/guides/location.md)). It has no subtype, floor, main area or price of its own. Instead, you send the shape of the project and the list of unit types.

### Project layout

**complex\_mode** `string`

The kind of project: `blocks` (apartment buildings), `houses` or `offices` (office buildings). If you leave it out, the floor rules for apartment buildings apply.

**reg\_s** `integer`

The number of basements, from 0 to 20.

**reg\_d** `integer`

The semi-basement: `1` if there is one, `0` if not.

**reg\_p** `integer`

The ground floor: `1` if there is one, `0` if not.

**reg\_e** `integer`

The number of floors, from 0 to 200.

**top\_level** `string`

The top level: `attic`, `roof_space` (loft) or `none`.

**house\_regime** `string`

The height of the houses, with `complex_mode: houses`: `ground`, `ground_plus_1`, `ground_plus_1_attic` or `ground_plus_2`.

**sections\_count** `integer`

The number of sections, from 1 to 40.

**phases\_count** `integer`

The number of project phases, from 1 to 20.

The number of floors is required. For apartment and office buildings, send at least the ground floor (`reg_p: 1`) or one floor (`reg_e` above 0); otherwise you get `complex_regime_missing` on `/reg_e`. For houses, send `house_regime`; otherwise you get `complex_regime_missing` on `/house_regime`.

### Delivery

**project\_stage** `string`

The project's stage: `launch`, `under_construction`, `finished` or `mixed` (phases at different stages).

**delivery\_quarter** `integer`

The delivery quarter, from 1 to 4.

**delivery\_year** `integer`

The delivery year, from 2000 to the current year plus 10.

A delivery date in the past is rejected with `delivery_in_past` on `/delivery_quarter`, unless `project_stage` is `finished`. The current quarter is accepted.

### Unit types

`unit_types` lists the project's unit types, up to 50 rows. Each row describes a group of similar units.

**unit\_types\[].kind** `string`

The unit type: `studio`, `apartment`, `penthouse`, `house`, `duplex`, `triplex`, `villa`, `commercial`, `office`, `parking` or `storage` (a storage unit).

**unit\_types\[].label** `string`

Your own name for the type, up to 120 characters, for example `Tip A`. Required only when `kind` is missing.

**unit\_types\[].rooms** `integer`

The number of rooms, from 0 to 20. A `studio` always has one room, and `commercial`, `office`, `parking` and `storage` have no rooms.

**unit\_types\[].floors** `string`

The floors the units are on, as a `from|to` range of level codes: `ground|floor_4`, `floor_1|floor_8`. Write a single level without the `|` (`floor_8`). Plain numbers also work (`1|8`). Leave it out for houses.

**unit\_types\[].area\_sqm** `number`

The area, from 1 to 10,000 m², with up to two decimals. When the units have different areas, send the smallest one.

**unit\_types\[].area\_sqm\_to** `number`

The largest area, when the type covers a range.

**unit\_types\[].units\_count** `integer`

How many units of this type the project has, from 1 to 10,000.

**unit\_types\[].price\_from** `integer`

The starting price for this type, in the currency set in `price_currency`.

At least one row must be complete, meaning it has `kind` or `label`, plus `area_sqm`, `units_count` and `price_from`. With no complete row, you get `complex_needs_complete_type` on `/unit_types`.

A row's floors must exist in the project's number of floors. With `reg_p: 1` and `reg_e: 8`, the range `floor_1|floor_10` is rejected with `floor_range_invalid` on `/unit_types/0/floors`. The attic or loft can be part of a range only if you sent it in `top_level`.

### Price

Do not send `price`; Housera calculates it. When the development has available units (active, unreserved listings linked to it, with the same transaction), its price is the price of the cheapest unit. Reserved, sold and unpublished units are left out. Parking spots and storage units count only when the development has no other unit available. As long as no unit is available, the price is the lowest `price_from` among the complete rows. The price updates on its own after a unit changes. If your prices are in a currency other than euro, put the currency in `price_currency`, as for any listing.

## Example: buildings

```json theme={null}
{
  "type": "complex",
  "transaction": "sale",
  "title": "Ansamblul Nord, apartamente noi în Copou, Iași",
  "description": "Două blocuri cu parter și opt etaje, la zece minute de Parcul Copou. Apartamente cu una, două și patru camere, cu parcare subterană și spații verzi între clădiri.",
  "city": "Iași",
  "county": "Iași",
  "area": "Copou",
  "street": "Strada Sărărie",
  "street_number": "40",
  "latitude": 47.1712,
  "longitude": 27.5749,
  "complex_mode": "blocks",
  "project_stage": "under_construction",
  "delivery_quarter": 4,
  "delivery_year": 2027,
  "sections_count": 2,
  "reg_s": 1,
  "reg_p": 1,
  "reg_e": 8,
  "top_level": "roof_space",
  "unit_types": [
    { "kind": "studio", "rooms": 1, "floors": "floor_1|floor_7", "area_sqm": 38, "area_sqm_to": 42, "units_count": 16, "price_from": 59000 },
    { "kind": "apartment", "rooms": 2, "floors": "floor_1|floor_7", "area_sqm": 54, "area_sqm_to": 60, "units_count": 48, "price_from": 72000 },
    { "kind": "penthouse", "rooms": 4, "floors": "floor_8", "area_sqm": 120, "units_count": 4, "price_from": 189000 }
  ]
}
```

`price` will be 59,000 EUR, the price of the studios.

## Example: houses

```json theme={null}
{
  "type": "complex",
  "transaction": "sale",
  "title": "Casele din Valea Lungă, cartier nou lângă Iași",
  "description": "Douăzeci și patru de case cu parter și etaj, fiecare cu curte proprie și loc de parcare. Drumurile interioare sunt asfaltate, iar utilitățile sunt trase la fiecare lot.",
  "city": "Miroslava",
  "county": "Iași",
  "street": "Strada Valea Lungă",
  "latitude": 47.1452,
  "longitude": 27.5126,
  "complex_mode": "houses",
  "house_regime": "ground_plus_1",
  "project_stage": "launch",
  "delivery_quarter": 2,
  "delivery_year": 2028,
  "unit_types": [
    { "kind": "house", "rooms": 4, "area_sqm": 120, "area_sqm_to": 135, "units_count": 18, "price_from": 145000 },
    { "kind": "duplex", "rooms": 3, "area_sqm": 98, "units_count": 6, "price_from": 118000 }
  ]
}
```

## After creation

A development goes through the same steps as any listing. It enters moderation with the `pending` status, takes its photos like any listing (see [Photos](https://api.housera.ro/en/guides/photos.md)), and you edit it with `PATCH /listings/{code}`. When you read the listing, the response includes `unit_types` with the saved rows. When you send `unit_types` in an edit, the whole list is replaced, so include every row.

## Development units

An apartment, a house, a commercial space or a parking spot in the development is published as a listing of its own, with its own type (`apartment`, `house`, `commercial` or `garage`), and linked to the development through the `complex` field, which takes the development's code.

**complex** `string`

The code (`code`) of the development the unit belongs to. On an edit, `null` takes the unit out of the development; if you leave the field out, the link stays as it was.

**unit\_ref** `string`

The unit's identifier within the development, up to 64 characters: the building or staircase and the number, for example `B2-14` or `Scara A ap. 7`. Housera stores it normalized, in capitals, without diacritics, without words such as "scara", "ap" or "bloc", and with `-` between the parts: `Scara A ap. 7` becomes `A-7`. It is never public. Only the company that published the unit reads it.

```json theme={null}
{
  "type": "apartment",
  "transaction": "sale",
  "title": "Apartament cu 2 camere în Ansamblul Nord, Copou",
  "complex": "HEWPUTA8",
  "unit_ref": "B2-14"
}
```

A key links units to its own company's developments: the active ones, those in moderation and the drafts. A project manager links only to their own projects. A key links to another company's active development only once the developer has approved the key's company as a partner, and then `unit_ref` is required. See [Partner agencies](https://api.housera.ro/en/guides/partners.md).

The link applies at once, on a published listing too, without waiting for moderation like the rest of an edit. It is part of the listing's version, so it changes the `etag`. The response to an edit that changes only the link is described in [The link to a development](https://api.housera.ro/en/concepts/editing.md#the-link-to-a-development).

A company lists a unit once per transaction: a second listing with the same `unit_ref` in the same development gets `unit_ref_taken`.

### The inventory

For a development, `GET /listings/{code}` and `GET /account/listings/{code}` return the `inventory` field, counted from the linked units:

```json theme={null}
"inventory": {
  "sale": {
    "source": "units",
    "available": 50,
    "reserved": 3,
    "sold": 12,
    "price_min": 96000,
    "price_max": 209042,
    "groups": [
      { "family": "apartments", "rooms": 2, "available": 30, "reserved": 1, "sold": 5,
        "area_min": 41, "area_max": 61, "land_min": null, "land_max": null,
        "floor_min": 1, "floor_max": 9, "price_min": 96000, "price_max": 155844 }
    ]
  },
  "rent": null
}
```

A unit keeps its own transaction, so a development for sale can also have units for rent. `inventory` has one object per transaction, `sale` and `rent`, with the same shape. The development's own transaction is always there; the other one is `null` until it has units. The development's `price` and counters come from its own transaction only. Under `rent`, prices are per month.

* `source` is `units` when the development has published units and `declared` while it has none. With `declared`, the counters are zero, `groups` is empty, and you read the project from `unit_types`.
* `available` counts the active units that are not reserved, `reserved` the active reserved ones, and `sold` the sold ones. A unit offered by several companies is counted once.
* `price_min` and `price_max` are the prices of the available units, in euros. Parking spots and storage units count toward the range only when the development has no other unit available.
* `groups` has one group per family (`apartments`, `houses`, `commercial`, `offices`, `parking`). A family whose units have different room counts is split by rooms, and `rooms` says how many rooms the group's units have; `rooms: 5` means 5 rooms or more. `rooms` is `null` when the family is not split: all its units have the same room count, or the family has no rooms (`commercial`, `offices`, `parking`). In a split family, the group with `rooms: null` holds the units with no room count. A group's ranges cover the units still on offer, available and reserved.

`inventory` holds numbers and ranges only. You read the units with `GET /listings?complex={code}` in the catalog or with `GET /account/listings?complex={code}` among your own listings. On a unit, the `complex` field names the development, with `code`, `title` and `url`.

The inventory can be read by the keys of the company that published the development and by partners with the `catalog:read` ability. A partner agency's key does not see it. See [What the agency key can read](https://api.housera.ro/en/guides/partners.md#what-the-agency-key-can-read).

The less common project fields (finishes, technical details, surroundings, energy consumption) are in the [vocabulary](https://api.housera.ro/en/vocabulary.md), among the fields that list `complex` in their types.

## The developer and the marketer

On a development, `GET /listings/{code}` and `GET /account/listings/{code}` also return the company that builds the project (`developer`) and the company that markets it (`marketer`). On every other listing type, both are `null`. They are read-only: you do not send them when you create or edit a listing.

```json theme={null}
"developer": {
  "name": "Construct Nord SRL",
  "country": "RO",
  "tax_id": "12345678",
  "verified": true,
  "url": "https://housera.ro/agentii/construct-nord"
},
"marketer": {
  "name": "Imobiliara Sud",
  "kind": "agency",
  "url": "https://housera.ro/agentii/imobiliara-sud"
}
```

* `marketer` is the development's own company: it publishes the page and receives the enquiries. `kind` is `agency` when an agency markets the project and `developer` when the developer markets it itself. In that case, `developer` and `marketer` name the same company.
* `developer` is `null` while Housera does not know who builds the project.
* `verified` is `true` when Housera has checked the company's details.
* `tax_id` is the developer's tax ID. It is there only when the company is verified and is a legal entity. The tax ID of a sole trader (PFA) or an individual enterprise belongs to a person, so for those the field is `null`.
* `url` is the company's page on Housera. For the developer it is `null` when the company has no Housera account.

## The marketing mandate

On an agency's development, `GET /account/listings/{code}` also returns the agency's mandate on the project, in `mandate`. You can only read it: a mandate is requested, confirmed and ended in the portal alone, and `mandate`, `developer` or `marketer` sent in a write get the `unknown_field` warning. On a development its developer markets itself, and on every other listing type, `mandate` is `null`.

```json theme={null}
"mandate": {
  "status": "confirmed",
  "decided_via": "developer",
  "valid_until": "2027-12-31"
}
```

* `status` is `requested` (waiting for a decision), `confirmed`, `refused`, `withdrawn` (the agency withdrew its request), `revoked` or `expired`. The development is public only while the mandate is `confirmed`.
* `decided_via` says who decided: `developer` (the developer, from its own account), `moderator` (a Housera moderator) or `legacy` (a mandate with no recorded decision). It is `null` until a decision is made.
* `valid_until` is the contract's end date, or `null` when the contract has none.

The developer can take the development over in the portal once the mandate has been decided. From then on the development is the developer's: the agency's keys get `404` on it, and the agency's units either stay linked as a partner's or leave the development, as the developer chooses. The events `complex.mandate_confirmed`, `complex.mandate_ended` and `complex.taken_over` tell you about each step. See [Webhooks](https://api.housera.ro/en/webhooks.md).


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