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

# Introduction

> Publish and manage real estate listings on Housera from your CRM or your app.

The Housera API allows you to publish, edit, and withdraw real estate listings directly from your system, without going through the form on the site. You receive back the status of each listing, the result of moderation, and any changes made in the meantime in the portal.

## Who it's for

<CardGroup cols={3}>
  <Card title="Agents" icon="building">
    You publish all your stock from one place. Listings appear under the agency name, just like when they are added by an agent from the account.
  </Card>

  <Card title="Owners" icon="house">
    Do you have a few properties in a spreadsheet or a custom app? You publish them with a key from your account.
  </Card>

  <Card title="CRMs" icon="plug">
    You synchronize your clients' listings by the id from the CRM, listen to webhooks, and reconcile daily.
  </Card>
</CardGroup>

## The same rules as the Housera form

There are no special rules for the API. A listing sent via the API goes through exactly the same checks as one completed in the form on housera.ro:

* **what is mandatory** for each type of property (an apartment has a floor, a house has land, a plot has area);
* **what values are allowed** for each field;
* **checks between fields** (the floor does not exceed the number of floors, bedrooms are not more than rooms);
* **moderation:** any new listing is checked by a person before it appears in search.

What you can publish from the account can also be published via API. What the form rejects, the API rejects immediately and with a stable error code.

## How the flow looks

<Steps>
  <Step title="You create a key">
    From your account, at [Settings → API](https://housera.ro/setari/api). Start with a sandbox key.
  </Step>

  <Step title="You check your mapping">
    `POST /listings/validate` applies all the rules without writing anything. You fix what it signals until you receive `{"valid": true}`.
  </Step>

  <Step title="You publish">
    `POST /listings` (or `PUT /listings/ref/{ref}`, if you are working with your ids). The listing enters moderation, with status `pending`.
  </Step>

  <Step title="You add the pictures">
    `PUT /listings/{code}/photos`, with public URLs or with files uploaded directly.
  </Step>

  <Step title="You find out the result">
    You receive a webhook `listing.published` or `listing.rejected`. If your endpoint was down, recover from `GET /events`.
  </Step>
</Steps>

## Addresses

| Environment | Base Address |
| - | - |
| Sandbox | `https://staging.housera.ro/api/v1` |
| Production | `https://housera.ro/api/v1` |

All requests use HTTPS and JSON. Each response has the header `X-Request-Id`, after which you find the request in [API log](/en/log).

## Next steps

<CardGroup cols={2}>
  <Card title="The first listing in 5 minutes" icon="rocket" href="/en/quickstart">
    From key to a listing in moderation, with examples in curl, PHP, JavaScript, and Python.
  </Card>

  <Card title="The fields of a listing" icon="list" href="/en/guides/listing-payload">
    What you send for an apartment, a house, a land or a commercial space.
  </Card>

  <Card title="Moderation and statuses" icon="shield-check" href="/en/concepts/moderation">
    What happens to a listing after you send it and how you find out the result.
  </Card>

  <Card title="For CRMs" icon="arrows-rotate" href="/en/crm">
    The recommended flow for robust synchronization.
  </Card>

  <Card title="Webhooks" icon="bell" href="/en/webhooks">
    Events, the signature, and retries.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/en/errors">
    The error format and all the codes you branch on.
  </Card>
</CardGroup>

<Note>
  Besides your listings, with a key with access `listings:read` you can also read the public catalog of active listings: `GET /listings` and `GET /listings/{code}`. The details are in the API reference.
</Note>


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