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

# Partner agencies

> How an agency sells the units of a developer's development: the partnership, linking through the API, and what happens when the partnership ends.

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.

```json theme={null}
{
  "data": [
    {
      "id": 42, "side": "agency", "status": "approved", "note": "Avem clienți pentru două camere.",
      "created_at": "2026-11-04T09:12:00+00:00", "decided_at": "2026-11-04T11:30:00+00:00", "ended_at": null,
      "complex": { "code": "HEWPUTA8", "title": "Copou Park", "url": "https://housera.ro/anunt/hewputa8/iasi/copou-park" },
      "developer": { "name": "Dezvoltator Nord" }, "agency": { "name": "Casa Bună" },
      "units": { "linked": 3, "active": 2 }, "leads": null
    }
  ]
}
```

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

```bash theme={null}
curl -X POST "https://housera.ro/api/v1/partnerships/42/revoke" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "confirm": "Casa Bună", "note": "Încheiem colaborarea pe acest proiect." }'
```

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](https://api.housera.ro/en/guides/projects.md#taking-a-unit-out-of-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`.

```bash theme={null}
curl -X PATCH "https://housera.ro/api/v1/listings/K3TQ8WZA" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "complex": "HEWPUTA8", "unit_ref": "B2-14" }'
```

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](https://api.housera.ro/en/guides/complex.md#development-units).

A key links within its own company, the company of the account that created it. See [Which listings each key can access](https://api.housera.ro/en/concepts/access.md).

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

```bash theme={null}
curl -X PATCH "https://housera.ro/api/v1/listings/R7MXQ2PL" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "complex": "HEWPUTA8", "unit_ref": "B2-14" }'
```

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](https://api.housera.ro/en/crm.md#developments).

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

| Event | Who receives it |
| - | - |
| `partnership.requested` | the development's company |
| `partnership.withdrawn` | the development's company |
| `partnership.approved`, `partnership.rejected` | the agency |
| `partnership.revoked`, `partnership.ended` | the agency and the development's company |
| `listing.complex_linked`, `listing.complex_unlinked` | the company that published the unit |
| `complex.mandate_confirmed`, `complex.mandate_ended` | the agency that markets the development |
| `complex.taken_over` | the agency and the developer |

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](https://api.housera.ro/en/webhooks.md).


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