Skip to main content
An API key acts on behalf of an account and can access exactly the listings that account manages in the Housera portal. This page explains what that means for each role, both for a key the account creates for itself and for a connection given to an integrator. In these pages, “company” is the entity a key or a connection is bound to: the agency or property developer the account works in. “Agency” only names the account type.

Two kinds of keys

An account creates its own key in Settings → API and uses it in its own system. Individuals, agencies with their own software and property developers work this way. An integrator connection is created when the account accepts a CRM through Connect with Housera. The integrator gets an API key tied to its application. The account sees the connection in Settings → API, under Connected applications, and can revoke it there at any time. Every key is bound to a company: the company the account works in when it creates its own key or approves an integrator connection. An account without a company has keys without a company. The API reads and writes only within the key’s company.

By the account’s role

For a listing the key cannot access, the API returns 404 not_found, just as for a listing that does not exist. The rule is the same for lists, reads, edits, photos and status changes. A listing’s events (GET /events and webhooks) go to the agent who has the listing and to the company’s agency owner and administrators, each through their own key. A branch manager sees the branch’s listings in the list but does not receive their events. A deleted listing’s events stay within its company. If a listing is reassigned to another agent in the portal, the agency owner and administrators can still access it, and so can their connections. Only the agent who had it before loses access.

Suspended or closed company

While the key’s company is suspended, the key no longer sees the team. The agency owner, administrators and managers keep the listings and client requests they handle themselves, as in the portal, and events about colleagues’ listings and requests no longer reach them. After reactivation, access comes back without you doing anything. When the company closes, its members leave it: the key keeps the account’s listings, hidden along with the company, and its client requests from outside the company. A new key cannot be bound to a suspended or closed company.

One account, one company

A company account works in one company only. Someone who works for two companies has two accounts, each with its own email address and its own keys. The Settings → API page shows the company on each key. When a person leaves the company, the keys bound to it get 401 unauthenticated. They don’t reach the company the account joins later either: the person creates a new key there.

Your IDs (external_ref)

Where an external_ref has to be unique depends on the role:
  • for the agency owner and administrators, the ID is unique within the company, so one company CRM writes for everyone;
  • for an agent or a manager, the ID is unique within their own space, separate from their colleagues’;
  • for an account without a company, the ID is unique within the account;
  • an integrator always has its own IDs, separate from the account’s and from other integrators’.
In responses and events, external_ref is visible only to a key in the space where it was set, that is, a key that would find it with GET /account/listings/ref/{ref}. For every other key (the account’s own key, another integrator’s connection, a colleague’s key with a different space) the field is null. See Identifiers for details.

Client requests

With the leads:read permission, a key reads the client requests the account sees in the portal. The agency owner and administrators read the whole company’s requests, a manager reads the branch’s, and an agent reads the ones they are handling. See Client requests.

Developments and partnerships

A key links units only to its own company’s developments and to the developments of companies that approved it as a partner. A partnership is requested by the agency’s owner or an administrator. On the development’s side, the owner, an administrator or the project’s manager decides. Another member’s key gets 404. A partnership’s events (partnership.*) and a mandate’s (complex.*) reach only the keys bound to the company they concern, those of its owner and administrators. Once the developer takes a development over, it no longer belongs to the agency: the agency’s keys get 404 on it, as on any other company’s listing. See Partner agencies and Developer projects.

What no key gives

  • The platform catalog (GET /listings) requires the catalog:read permission, which only Housera grants.
  • A key cannot do anything the account cannot do in the portal. An agency account cannot publish residential developments, and a company that has not been approved cannot publish until it is.