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

# The company and its team

> How you read the company's details, the people on its team and its offices, and which events you get when the team or the company changes.

Through the API you read the company the key works in: its details, the people on its team and its offices, under the same rules as the Team and Offices pages in the portal. This is how you match the colleagues in your CRM with the ones in Housera and find the email you send as `agent` on a listing or as `agent_email` to `POST /leads/{id}/assign`.

The API only reads. Invitations, roles, moving someone to another office, deactivating them and removing them from the team happen in the portal. When something changes, you get an event (see [Team and company events](#team-and-company-events)).

All three calls need the `listings:read` permission.

## The company

`GET /account/firm` returns the company the key works in.

```json theme={null}
{
  "data": {
    "id": 47,
    "name": "Casa Bună",
    "kind": "agency",
    "status": "approved",
    "legal_name": "Casa Bună Imobiliare SRL",
    "tax_id": "12345678",
    "email": "contact@casabuna.ro",
    "phone": "+40232100200",
    "website": "https://casabuna.ro",
    "url": "https://housera.ro/agentii/casa-buna",
    "suspended_until": null,
    "closes_at": null,
    "merges_into": null
  }
}
```

| Field | What it holds |
| - | - |
| `kind` | `agency` for an agency, `developer` for a property developer. |
| `status` | The company's status on Housera: `approved`, `suspended`, `pending` or `needs_info` (under review), `rejected` or `closed`. |
| `legal_name`, `tax_id` | The registered name and the tax code. |
| `url` | The company's public page. `null` while the company is not approved. |
| `suspended_until` | Until when the company is suspended. `null` if the suspension lasts until its cause is resolved, or if the company is not suspended. |
| `closes_at` | The date Housera closes the company or merges it into another, after 30 days' notice. `null` if nothing is scheduled. |
| `merges_into` | The company it will be merged into, with `id` and `name`, when a merge is scheduled. |

An account that works in no company, or that has left the key's company, gets `404`. A suspended company can still be read, with `status: suspended`.

## The team

`GET /account/members` returns the people on the team, with cursor pagination, in the order they joined the company.

```json theme={null}
{
  "data": [
    {
      "id": 311,
      "name": "Maria Popescu",
      "email": "maria.popescu@casabuna.ro",
      "phone": "+40740123456",
      "role": "agent",
      "position": "Agent imobiliar",
      "office": { "id": 12, "name": "Tătărași" },
      "projects": [],
      "active": true,
      "has_account": true,
      "joined_at": "2026-03-02T09:10:00+00:00"
    }
  ],
  "meta": { "next_cursor": null }
}
```

| Field | What it holds |
| - | - |
| `id` | The colleague's id on the team. You also find it in the `member.*` events. |
| `name` | The colleague's approved public name, the same as on the company's page and in a request's `agent.display_name`. Without an approved name, the name on the team. |
| `email`, `phone` | The colleague's contact details. You get them only if you also see them in the portal (see below); otherwise they are `null`. |
| `role` | `owner`, `admin`, `manager` or `agent`. `null` for a colleague who came from a CRM and has no account yet. |
| `office` | The office, with `id` and `name`. |
| `projects` | At a developer: the codes of the developments they work on. The owner and admins work on all of them, so their list is empty. |
| `active` | `false` for a deactivated colleague: they stay on the team, but have no access and get no requests. |
| `has_account` | `false` for a colleague who came from a CRM and has not made an account yet. |

What the key sees depends on the account's role, as on the Team page:

| Role | Whom they see | Email and phone |
| - | - | - |
| the owner or an admin | the whole team | everyone's |
| a manager | the people of their office (at a developer, of their projects) | theirs |
| an agent | the whole team | only their own |

Colleagues who left the company no longer appear. While the company is suspended or the account is deactivated, the list is empty, as in the portal.

## The offices

`GET /account/offices` returns the company's offices, the head office first, then the others by name. A developer has no offices, since its teams are on projects, so its list is empty.

| Field | What it holds |
| - | - |
| `id` | The office's id. Send it as `office` to `GET /leads`. |
| `name` | The office's name. |
| `kind` | `main` for the head office, `branch` for the others. |
| `address` | The address, in parts: `street`, `number`, `city`, `county`, `postal_code`, `country`. |
| `phone`, `email` | The office's contact details. |
| `members` | How many colleagues work there now, not counting deactivated ones. |

## Team and company events

When the team or the company changes, you get an event, on your webhook and in `GET /events`. They start in the portal and in Housera's moderation.

| Event | When |
| - | - |
| `member.joined` | Someone joined the team: they accepted an invitation or their access request was approved. |
| `member.role_changed` | A colleague's role changed. `previous_role` is the role they had before. |
| `member.office_changed` | A colleague moved to another office. `previous_office` is the office they were in before. |
| `member.deactivated` | A colleague was deactivated: they stay on the team, but no longer have access or get requests. |
| `member.reactivated` | A deactivated colleague was reactivated. |
| `member.removed` | A colleague left the team. `reason` says how: `removed` (taken off by the owner or an admin), `left` (left on their own) or `account_deleted` (deleted their account). Their listings and requests went to the colleague in `handed_to`, or the requests went to “To take” (`inbox: true`). |
| `firm.suspended` | Housera suspended the company. `until` is the date the suspension ends, or `null` if it lasts until its cause is resolved. |
| `firm.reactivated` | The company was reactivated after a suspension. |
| `firm.closure_scheduled` | Housera scheduled the company's closure, with notice, on the date in `closes_at`. If the closure is called off, you get the event again, with `cancelled: true` and `closes_at: null`. |
| `firm.closed` | The company was closed. |
| `firm.merge_scheduled` | Housera scheduled the merge of the company (`firm`) into another (`into`), on the date in `closes_at`. Both companies get it. If it is called off, again with `cancelled: true`. |
| `firm.merged` | The company `firm` was merged into the company `into`. Both get it. |

`member` in the `member.*` events has `id`, `name`, `email`, `role` and `office`, as in `GET /account/members`. When the colleague deleted their account (`reason: account_deleted`), `member` has only `id`, with no name or email. `handed_to` has `name` and `email`. `firm` and `into` have `id` and `name`.

The events reach the company's owner and admins, through the keys bound to the company that have the `listings:read` permission, and an integrator only if its connection is on that company. A manager or an agent does not get them. `firm.suspended`, `firm.closed` and `firm.merged` go out before the company loses its team, and the key bound to the company can still read them in `GET /events`.

Integrators' webhooks get them automatically. On a webhook from Settings → API you tick them, since they do not follow from another event.

> [!WARNING]
>
> Your colleagues' emails and phone numbers are personal data. Keep them only as long as you need them to match the colleagues in your CRM with the ones in Housera.


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