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

# Marketing mandates

> How you read your company's marketing mandates, as an agency or as a developer, and which events you get when a mandate asks you to take a step.

A residential development published by an agency needs a marketing mandate confirmed by its developer. Through the API you read your company's mandates, under the same rules as the Mandates screen in the portal: an agency sees the mandates it asked for, and a developer the ones that name it, including its developments marketed by an agency.

The API only reads. Declaring a mandate with its contract, confirming, refusing, checking a renewal, revoking and taking a development over happen in the portal. The contract is not read through the API. When a mandate asks you to take a step, you get an event (see [Mandate events](#mandate-events)).

Only the company's owner and admins read the mandates, with a key bound to the company that has the `listings:read` permission. Any other key gets `403 forbidden` on the list and `404` on a mandate.

## The list of mandates

`GET /account/mandates` returns the company's mandates, with cursor pagination, oldest first. With `status` you get only the waiting ones (`requested`), the confirmed ones (`confirmed`) or the history (`closed`: refused, withdrawn, revoked and expired).

```json theme={null}
{
  "data": [
    {
      "id": 812,
      "side": "agency",
      "status": "confirmed",
      "step": "confirmed",
      "legacy": false,
      "complex": { "code": "K7Q2M9PA", "title": "Copou Park", "url": "https://housera.ro/anunt/k7q2m9pa/iasi/copou-park" },
      "agency": { "id": 47, "name": "Casa Bună" },
      "developer": { "name": "Construct Nord", "legal_name": "Construct Nord SRL", "tax_id": "87654321", "on_platform": true },
      "valid_until": "2027-06-30",
      "decided_via": "developer",
      "created_at": "2026-10-02T08:00:00+00:00",
      "decided_at": "2026-10-03T11:20:00+00:00",
      "ended_at": null
    }
  ],
  "meta": { "next_cursor": null }
}
```

`GET /account/mandates/{id}` returns a single mandate, in the same shape. A mandate the key does not see gets `404`, like one that does not exist.

| Field | What it holds |
| - | - |
| `side` | Which side your company is on: `agency` (the agency that markets the development) or `developer` (its developer). |
| `status` | `requested` (waiting), `confirmed`, `refused`, `withdrawn` (by the agency), `revoked` or `expired`. |
| `step` | Where the mandate stands now (see below). |
| `legacy` | `true` for a mandate from before the current rules, which the agency has to declare with the developer and the contract. |
| `complex` | The development, with `code`, `title` and `url`. |
| `agency` | The agency that markets the development, with `id` and `name`. |
| `developer` | The developer: `name`, the registered name, the tax code (only for a legal entity verified in the register, otherwise `null`) and `on_platform`, `true` when the developer has its own company on Housera and decides the request. |
| `valid_until` | The day the contract ends. `null` if it has no end date. |
| `decided_via` | Who decided: `developer`, `moderator` (Housera's moderation) or `legacy`. `null` while the request is waiting. |
| `decided_at`, `ended_at` | When the mandate was confirmed or refused, and when it ended. |

The values of `step`:

* `awaiting_developer`: the request waits for the developer's answer;
* `awaiting_moderation`: Housera's moderation decides the request, for example because the developer is not on Housera or did not answer in time;
* `better_contract_requested`: the agency was asked for a better contract;
* `to_declare`: a mandate from before, which the agency has to declare;
* `renewal_to_check`: the agency sent a renewed contract, which the developer has to check;
* `confirmed`: the mandate is confirmed and waits for nothing;
* `ended`: the mandate has ended.

## Mandate events

When a mandate asks you to take a step, you get an event, on your webhook and in `GET /events`. They start in the portal, in Housera's moderation or in the daily check of the deadlines, like the notifications the owner and admins get.

| Event | Who gets it | When | Extra fields in `data` |
| - | - | - | - |
| `complex.mandate_requested` | the developer | An agency asked for the mandate on one of its developments. | `agency` (`id`, `name`) |
| `complex.mandate_withdrawn` | the developer | The agency withdrew its request. | – |
| `complex.mandate_renewal_due` | the developer | The agency sent a renewed contract to check. | – |
| `complex.mandate_expiring` | the agency | The contract ends soon: 30 days and then 7 days before. | `valid_until` |
| `complex.mandate_better_contract_requested` | the agency | The developer or the moderation asked for a better contract. | `note` (what was asked) |
| `complex.mandate_restricted` | the agency | The moderation stopped the agency's mandate requests for a while. | `until` |

All of them have `mandate_id`, `complex` (`code`, `title`, `url`) and `status`, the mandate's status when the event happened, except `complex.mandate_restricted`, which is about the agency, not a mandate, and has only `until`. With `mandate_id` you read the mandate with `GET /account/mandates/{id}`.

The events reach the company's owner and admins, through the keys bound to the company with the `listings:read` permission, and an integrator only if its connection is on that company. A webhook that gets `complex.mandate_confirmed` gets them too, without ticking them.

`complex.mandate_confirmed`, `complex.mandate_ended` and `complex.taken_over` stay as they were. You find them in [Webhooks](https://api.housera.ro/en/webhooks.md).


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