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:
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:
- 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.
- 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.
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.
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:
- 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:
- 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}.
