Skip to main content
An agency can sell apartments or houses in a developer’s development. It publishes each unit as a listing of its own and links it to the development, and the unit then shows on the development page next to the developer’s units. The listing stays the agency’s: client requests go to the agency, and the developer sees only how many there were, without contact details.

The partnership

The partnership is requested and decided in the Housera portal or through the API, under the same rules. Each side gets the portal notification and the partnership.* event that concerns it.
1

The agency asks

The agency’s owner or an administrator asks for the partnership, with an optional message. The request can be made for the active development of any approved company that has an owner or an administrator.
2

The development's company decides

The owner, an administrator or the project’s manager of the development’s company approves or declines the request. That company is the developer, or the agency that markets the development under a mandate. Until it is decided, the agency can withdraw its request.
3

The agency links its units

Once approved, any member of the agency links units to the development, in the portal or through the API.

Partnerships through the API

Reading needs the listings:read permission, and the request and the decisions need listings:write. GET /account/partnerships returns the partnerships of the key’s company, newest first, on both sides: those your agency asked for (side: agency) and those on your company’s developments (side: developer). You can narrow them with side, status and complex, the development’s code. A partnership’s id is the one in the partnership.* events. Any member of the company can read the partnerships your agency asked for. Those on your developments can be read only by the company’s owner, its admins and a project’s manager, for that manager’s projects. For other members the list leaves them out.
status is pending, approved, rejected, withdrawn, revoked or ended. note is the agency’s message. When the developer rejects or revokes with a reason, note becomes their reason. units counts the agency’s listings linked to the development. leads is the number of client requests they brought and appears only on the developer’s side. The clients’ data stays with the agency.

The agency’s side

With the key of the agency’s owner or an administrator:
  • GET /partnerships/developments?q=copou searches the developments you can ask for, by name (at least 2 characters, at most 20 results). Each result has code, title, url, the locality, the developer and, in partnership, the request or partnership you already have.
  • POST /partnerships asks for the partnership, with complex (the development’s code) and an optional note of up to 500 characters. The response is 201, with the partnership pending.
  • POST /partnerships/{id}/withdraw withdraws a request that is still waiting.
A refused request gets 409, with the reason in code: partnership_unavailable (the development doesn’t take requests now, or it is your own company’s), partnership_already_open (you already have a pending request), partnership_already_partner (you are already a partner), partnership_paused (the developer rejected several of your requests recently; try again later) or partnership_too_many (you have too many pending requests). An unknown development code gets 422 complex_not_found.

The developer’s side

With the key of the owner, an administrator or the project’s manager:
  • POST /partnerships/{id}/approve approves the request.
  • POST /partnerships/{id}/reject rejects the request, with an optional note the agency reads.
  • POST /partnerships/{id}/revoke ends an approved partnership. All of the agency’s units leave the development and stay published as ordinary listings. A revocation can’t be undone. That is why, as in the portal, you confirm it with the agency’s name in confirm, written exactly as in agency.name. Another name gets 422 partnership_confirm_mismatch on /confirm.
Each action answers with the updated partnership. If the request was answered or the partnership ended in the meantime, you get 409 partnership_closed. On approval, 409 partnership_unavailable means the development is no longer active or the agency is no longer approved. Whoever can’t decide on that partnership gets 404. You take a partner’s units out one at a time from the project.

Linking through the API

With the agency’s key, send complex, the development’s code, and unit_ref, the unit’s identifier, to POST /listings, PUT /listings/ref/{ref} or PATCH /listings/{code}. On a partner agency’s unit, unit_ref is required: without it you get unit_ref_required on /unit_ref.
The response shows the link in complex, with linked_by: "partner", and the normalized identifier in unit_ref. On an active listing, a request that changes only the link gets 200: the link applies at once and nothing goes to moderation. Without an approved partnership, another company’s development answers complex_not_linkable, and a development the key cannot see answers complex_not_found. The full rules are in Development units. A key links within its own company, the company of the account that created it. See Which listings each key can access.

Listings imported from a CRM

Listings that Housera takes from the agency’s CRM are edited only in the CRM. Their link to a development and their unit_ref are not part of the listing’s content, though. You change them through the API with a PATCH /listings/{code} that sends only complex and unit_ref, like Link to development in the portal:
The link applies at once, under the same rules as on a listing published directly, and the response is 200 with the listing. Later imports don’t touch it. A PATCH that also sends another field gets 403 forbidden and nothing is saved. If the link comes from the import, the link and unit_ref change only in the CRM: you get 422 complex_link_from_import. See For CRMs.

What the agency key can read

The agency’s key cannot read the developer’s development or its inventory. GET /listings and GET /listings/{code} belong to the platform catalog and need the catalog:read ability, so you get 403 missing_ability. GET /account/listings/{code} returns only the agency’s own listings, so on the development’s code it answers 404. The agency reads the units it linked with GET /account/listings?complex={code}. Each unit has the complex field, with code, title, url and linked_by. You find the development’s code with GET /partnerships/developments, with GET /account/partnerships or in the portal, where it is in the address of the development’s page, right after /anunt/. In https://housera.ro/anunt/hewputa8/iasi/..., the code is hewputa8. The API accepts it in lower or upper case.

Taking a unit out of the development

A unit leaves the development in five ways:
  • the agency sends complex: null or takes it out in the portal;
  • the developer removes the unit from the development, in the portal or through the API;
  • the developer revokes the partnership, in the portal or through the API, and all of the agency’s units leave the development;
  • Housera ends the partnership for example because the development is no longer active;
  • the mandate of the agency that marketed the development ended: the developer revoked it, or took the development over and took the agency’s units out (reason: mandate_revoked).
The listing stays published and loses only its link and its unit_ref. Unless you sent complex: null yourself, you get listing.complex_unlinked, with the cause in reason and the new etag.

Webhooks

The partnership events reach the company’s owner and administrators, through the keys bound to that company and holding listings:read. Their shape is in Webhooks.