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. 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.
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.
What you send
A development has the fields every listing has:type, transaction, title, description and the location (latitude, longitude, city, street; see Location). 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
The kind of project:
blocks (apartment buildings), houses or offices (office buildings). If you leave it out, the floor rules for apartment buildings apply.The height of the houses, with
complex_mode: houses: ground, ground_plus_1, ground_plus_1_attic or ground_plus_2.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
The project’s stage:
launch, under_construction, finished or mixed (phases at different stages).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.
The unit type:
studio, apartment, penthouse, house, duplex, triplex, villa, commercial, office, parking or storage (a storage unit).Your own name for the type, up to 120 characters, for example
Tip A. Required only when kind is missing.The number of rooms, from 0 to 20. A
studio always has one room, and commercial, office, parking and storage have no rooms.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.The area, from 1 to 10,000 m², with up to two decimals. When the units have different areas, send the smallest one.
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 sendprice; 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
price will be 59,000 EUR, the price of the studios.
Example: houses
After creation
A development goes through the same steps as any listing. It enters moderation with thepending status, takes its photos like any listing (see Photos), 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.
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.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.unit_ref is required. See Partner agencies.
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.
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:
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.
sourceisunitswhen the development has published units anddeclaredwhile it has none. Withdeclared, the counters are zero,groupsis empty, and you read the project fromunit_types.availablecounts the active units that are not reserved,reservedthe active reserved ones, andsoldthe sold ones. A unit offered by several companies is counted once.price_minandprice_maxare 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.groupshas one group per family (apartments,houses,commercial,offices,parking). A family whose units have different room counts is split by rooms, androomssays how many rooms the group’s units have;rooms: 5means 5 rooms or more.roomsisnullwhen 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 withrooms: nullholds 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.
The less common project fields (finishes, technical details, surroundings, energy consumption) are in the vocabulary, 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.
marketeris the development’s own company: it publishes the page and receives the enquiries.kindisagencywhen an agency markets the project anddeveloperwhen the developer markets it itself. In that case,developerandmarketername the same company.developerisnullwhile Housera does not know who builds the project.verifiedistruewhen Housera has checked the company’s details.tax_idis 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 isnull.urlis the company’s page on Housera. For the developer it isnullwhen 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.
statusisrequested(waiting for a decision),confirmed,refused,withdrawn(the agency withdrew its request),revokedorexpired. The development is public only while the mandate isconfirmed.decided_viasays who decided:developer(the developer, from its own account),moderator(a Housera moderator) orlegacy(a mandate with no recorded decision). It isnulluntil a decision is made.valid_untilis the contract’s end date, ornullwhen the contract has none.
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.