Best practices
The rest of the documentation is organised by endpoint: each page answers "what does this do?". Useful once you already know what to call.
This section answers the other question, the first one: in what order? These are the complete flows, with the decisions you are going to have to make and what each step costs.
You will not find fields, error codes or payloads here — those live on each endpoint's page and are linked where relevant. If you are looking for "what does it return", go to the endpoint; if you are looking for "what do I call first", stay.
The flows
| When | ||
|---|---|---|
| Setting up a client | once per client | their record and the portal connection |
| Publishing a listing | every property | the base case: load, check, publish |
| Publishing a development | every development | it has an order of its own, worth knowing beforehand |
| Receiving enquiries | ongoing | the enquiries people leave on the listings |
| Taking things down | when applicable | taking a listing down, disconnecting an account, deleting a client: three different things |
| When something does not work | — | where to start looking |
The four rules that apply to all of them
1 · Some things are done ONCE and some EVERY TIME
This is the most expensive design mistake in an integration, because it does not fail: it simply makes three times as many calls as needed.
| Once per client | Every time |
|---|---|
| declaring their record | loading or updating a property |
| connecting their portal account | publishing, checking the status, taking down |
| mapping their zones (we do that) | — |
2 · Reading our system is free; asking the portal costs
The call allowance belongs to your client, they contract it with the portal, and your integration spends it. Each portal defines it its own way.
| Free | Spends one call from the allowance |
|---|---|
| checking an object | publishing and taking down |
| reading a property or listing them | asking the portal about the listing's status |
| reading the client's record and their stored plans | refreshing the plans against the portal |
⚠️ Errors spend too. An attempt rejected by the portal consumes the call all the same, so it pays to check first — which is free.
3 · Store two things on your side
- The
paIdwe return when you create a property. It is what you publish, read and take down with. If you lose it, you have the listing endpoint and you can look it up by your own code, but that is a step you did not need. - Which
clientRefyou operated with. It is how you tell us which client you are talking about, and you choose it: use the id you already have in your system.
4 · Retrying is safe, and you do not have to keep track
- Publishing again updates the listing, it does not create another one. It is how you reflect a change in price or photos.
- Taking down twice answers fine both times. You do not have to remember whether you already did.
- What is not idempotent is creating: two submissions of the same property are two properties.
Send your own code and use the
paIdwe return.
The portals
The methods are the same for every portal: you pass the portal in the route and nothing else changes. What does change per portal —how the account is connected, what allowance it has, what plans— is in Publication, and the flows here point there instead of repeating it.
Where a portal behaves differently, we say so with its name attached. If you read a figure or a plan name with no portal next to it, that is a mistake on our side: write to us.
If your app connects a single client
The flows are written for the general case, where your app operates on several clients and you tell us which one on each call. If your app is enabled for one only, the client is already fixed on our side and you can ignore that step: everything else is the same.