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

# Identifiers

> The Housera code, your id, the idempotency key, and reconciliation.

A listing has two identities: the code given to it by Housera and, optionally, the id from your system. You can use both.

## `code`, the Housera code

Each listing receives a public code of 8 characters upon creation, for example `HEWPUTA8`. It is the same code that appears in the listing's URL on the site and never changes.

You use it in all routes that refer to a specific listing:

```http theme={null}
GET    /account/listings/HEWPUTA8
PATCH  /listings/HEWPUTA8
POST   /listings/HEWPUTA8/pause
PUT    /listings/HEWPUTA8/photos
```

The code is case insensitive: `hewputa8` and `HEWPUTA8` lead to the same listing. In responses, it always comes in uppercase.

## `external_ref`, your id

If your system already has an id for each property, there's no need to keep the Housera code. You publish and update directly by your id:

```http theme={null}
PUT /listings/ref/CRM-10293
```

* **The first time** you send an id, the listing is created like at `POST /listings`, and you receive `201`.
* **Subsequent times**, the body applies to the existing listing, like an edit. See [Editing](/en/concepts/editing).
* **Reading** by your id: `GET /account/listings/ref/CRM-10293`.

The id appears in every listing and every event, in the field `external_ref` (`null` for listings created differently than through `PUT /listings/ref/{ref}`).

Rules for the id:

* between 1 and 100 characters: letters, digits, and `.` `_` `:` `/` `-`;
* it is unique **in your agency** (or in your account if you are not part of an agency). Two different agencies can both use `123` without conflict;
* an id with other characters receives `404`.

<Tip>
  Use an id that never changes in your system, not a sequential number from a list. If the id changes, Housera sees a new listing.
</Tip>

## `Idempotency-Key`, repeated requests

An unstable network may lose the response of a successful request. If you blindly repeat a `POST /listings`, you risk having two identical listings. The header `Idempotency-Key` prevents this:

```http theme={null}
POST /listings
Idempotency-Key: 6f1c2b0e-8a4d-4c3e-9b7a-2d5f1e0c9a11
```

* A repeated request with the same key, within the next **10 minutes**, returns the listing created by the first, without creating another one.
* The key is of your account: someone else using the same value does not affect your listings.
* The maximum length is 64 characters. A UUID generated for each new listing is the right choice.
* You generate the key **once per operation** and reuse it only for retries of that operation.

`PUT /listings/ref/{ref}` does not need `Idempotency-Key`: your id already plays this role. The same id sent twice never creates two listings.

## Reconciliation

Webhooks and events tell you what has changed. Once a day, it's still worth comparing everything you have with what is on Housera, to catch any differences. `GET /account/listings` accepts the parameter `fields`, which returns only the fields to compare:

```bash theme={null}
curl "https://housera.ro/api/v1/account/listings?fields=code,external_ref,etag,updated_at,status&per_page=100" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Accept: application/json"
```

```json theme={null}
{
  "data": [
    { "code": "HEWPUTA8", "external_ref": "CRM-10293", "etag": "\"9b2f6c1e4a7d3b8f0c5e2a1d6f4b7c9e\"", "updated_at": "2026-10-19T09:12:44+03:00", "status": "active" },
    { "code": "K7RM2QXP", "external_ref": "CRM-10301", "etag": "\"41d8cd98f00b204e9800998ecf8427e1\"", "updated_at": "2026-10-19T09:40:03+03:00", "status": "pending" }
  ],
  "links": { "first": null, "last": null, "prev": null, "next": "https://housera.ro/api/v1/account/listings?cursor=eyJ1cGRhdGVkX2F0Ijoi..." },
  "meta": { "path": "https://housera.ro/api/v1/account/listings", "per_page": 100, "next_cursor": "eyJ1cGRhdGVkX2F0Ijoi...", "prev_cursor": null }
}
```

* The list contains your listings in **any state** (and if you are the owner or admin of the agency, also those of your colleagues), ordered by `updated_at`.
* Go to the next page with `cursor` from `meta.next_cursor`, until this is `null`.
* `per_page` ranges from 1 to 100 (default 50). You can filter by state with `status`, for example `status=active`.

What you compare:

* **a `etag` different** from the one you know means that the listing has changed on Housera (an edit in the portal, a moderation): you read it all with `GET /account/listings/{code}`;
* **a listing that is missing** from the list has been deleted;
* **a `external_ref` that you cannot find** on Housera means that the listing did not make it: you send it again with `PUT /listings/ref/{ref}`.


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