Publishing a listing
The base case: one property, one portal. We assume the client already has their record and their portal account connected — if not, start with setting up a client, which is done only once.
The path
1 · load the property POST /properties → returns the paId
2 · check it POST /properties/verify free, and worth it
3 · publish PUT …/publication/{portal}
4 · how did it go? GET /properties/{paId} free · or ask the portal (costs)
5 · update PUT …/publication/{portal} the SAME call as step 3
6 · pay for position GET …/publication/{portal}/positioning depends on the portal
7 · take it down DELETE …/publication/{portal}
Steps 1 and 3 are the mandatory ones. Step 2 is free and saves you calls; 4 through 7 are as needed.
1 · Load the property
Before the first time it is worth reading two things: the property model —why the keys are the same in every country— and the JSON object, which is the contract for the fields.
POST /properties with your object. We return a paId:
store it, it is what you will do everything else with.
Send your own code in the object. It is your anchor: if you lose the paId, you recover it from
the listing endpoint by looking it up — the listing is
walked page by page, so for a large portfolio storing the paId is cheaper than searching for it.
Photos and floor plans travel inside the same object, not in separate calls. One single call
with everything. We download them, so the response may say they are still processing — that is
normal and does not block publishing. If one could not be downloaded, the images block says so and
it can be retried without sending the object again.
If you are a Mapaprop customer and generated your token from the app, this same step does
something more: the property goes into your Mapaprop account by itself when the photos finish
processing, without you asking for anything. It ends up loaded, not published — publishing it is
still step 3. The state of the creation travels in the mapaprop block and is explained in
Mapaprop.
And your own account is one of the destinations of step 3: it is published with
mapapropapi on the same route, it does not consume any portal quota, and it also publishes
to the networks you belong to. Step 2 does not apply: verifying is against the portals.
2 · Check it (free, and the best investment in the flow)
POST /properties/verify tells you, portal by portal,
whether that listing would go out — and what is missing if it would not. It asks the portal
nothing, so it spends no allowance and does not depend on the portal being up.
Why it pays: an attempt rejected by the portal spends the call all the same. Checking first is free, so the arithmetic is easy.
It separates two things, and the distinction matters:
- What is missing in the object → you fix that, in what you send.
- What is missing from the account (the plan, the branch) → that comes from the client's connection, not from the property. You do not need to send it when checking.
And it checks both catalogues: the zone, hierarchy included, and the attributes against the catalogue of the property's country. They are the errors that cost the most to discover late, because neither of them bounces: the property goes in all the same, and then it shows up in no search by location, or it is missing a feature. Looking at the property you cannot tell — which is why this step is worth it.
Use it before you even have the account connected. The checker works the same and tells you whether your object mapping is right, so you can have your integration ready before your client authorises.
3 · Publish
The only decision in this step: on portals that have publication plans, you choose which one to publish with. You can send it in the call or leave it stored in the property's configuration — and if you send both, the one in the call wins, so you can change plan without rewriting the property.
If the plan you asked for is not available, the response tells you which ones they do have. You do not need to look it up beforehand.
The other decision, and it is optional: which contact details this particular listing goes out with. By default it uses the ones in your client's record; if you want different ones —the agent who handles that property, their phone number— you send them in the same call. The agent's email address must belong to a user that exists in the portal account, and that is what your client's user list is for — its basic level does not use up any quota. ⚠️ If you send one the portal does not recognise, it does not return an error: it replaces it with the administrator's and publishes all the same.
And if the property is reserved, sold or rented, the listing reflects it on its own: the state travels inside the object and is applied in this very step — see the property's state on the portal. There is nothing else to call. ⚠️ But a property has ONE state or none: two of them on are rejected in step 2.
4 · Seeing how it went — and here there are two paths that are not the same
| What it tells you | Cost | |
|---|---|---|
GET /properties/{paId} | what we recorded about that publication | free |
GET …/publication/{portal} | what the portal says: whether it is online, its URL, the views | 1 call |
Read the free one first. Ask the portal when you need something only it knows —the listing's URL, the views— or when you suspect someone changed it on the portal's side.
⚠️ Do not poll the status in a loop. With 400 properties that is 400 calls from your client's allowance.
5 · Update
There is no endpoint for updating a publication: it is the same PUT as step 3. Calling it again
updates the listing instead of duplicating it.
So the flow for a price change is: you update the property → you publish again. Two calls, and the second is the one that reaches the portal.
But the portal needs to finish the previous publication before accepting the next one. If you publish and update in the same burst, the second call can fall inside that window and the portal rejects it.
It is temporary and we tell you so: the response carries how many seconds it is worth waiting. Wait and call again — you lost nothing and the listing is not duplicated.
⚠️ This is the decision worth taking in your code, not by hand: when we tell you the portal is still processing, retry with a wait instead of treating it as a failure. The publication endpoint has the exact contract of that response.
And there is a second decision, a design one: wait or ask. If you prefer not to wait blindly, you can ask the portal which stage it is at — the status check tells you that.
⚠️ For a standalone listing both paths work. For a development with many units they do not: there, asking misleads you, and the reason is in publishing a development.
Asking spends one call of your customer's quota; waiting is free. That is why the default recommendation does not change: on the processing window, retry with a wait. Checking the status is the alternative for whoever prefers knowing over waiting — and it is worth saving for when you need to decide something with that answer.
6 · Paying for position (optional, and not done the same way on every portal)
Up to here the listing is published. Where it shows in the results is a different decision, and the portals that charge for it do not charge at the same point in the flow: on some it is chosen when you publish —it travels with step 3— and on others afterwards, on the listing that is already online.
You do not have to know it by heart: ask. The GET is free and tells you.
GET …/publication/{portal}/positioning
PUT …/publication/{portal}/positioning
The GET always answers two things: what position is paid with on that portal, and where it is
chosen. From there, three paths:
What the GET tells you | What you do |
|---|---|
| it is chosen here | read → decide → PUT, as below |
| it is chosen when publishing | back to step 3: it travels with the publication, and the GET tells you in which field |
| the portal does not charge for it | nothing: there is no position to buy |
When it is chosen here, the order is read, decide, assign — never assign blind:
- The
GETtells you how much your client has left, where the listing stands today and, if you ask for it, what position it would get for each amount. - You decide (or your user does). We do not choose for them.
- The
PUTapplies it and hands you back the real position it ended up in.
?simulate= costs one call against your client's quota per value. Ask for the ones you are going
to show, not a whole curve "just in case".
Right after publishing there may be no data yet: the portal takes a moment to index the listing.
The balance and the position come back anyway; the simulation arrives with unavailable and its
reason. Ask again in a while.
Full detail: paying for position. What is specific to each portal —what it charges with, what quota it has— is in Publication.
7 · Take it down
DELETE …/publication/{portal} takes the listing down
from that portal. It is idempotent: if it was already gone, it answers fine all the same, so you
do not have to keep track.
And mind the distinction, which is the one that confuses the most: taking a listing down, disconnecting the account and deleting the client are three different things, and only the first one takes the publication down. It is covered in taking things down.
Order matters: what happens if you do it backwards
| If you… | We tell you like this |
|---|---|
| publish before the client has a record | the error says the client needs declaring, and how |
| publish before their account is connected | the error says that account needs connecting, with the portal named |
| publish a property you never loaded | we cannot find it by that paId |
All three are early errors with a name: they tell you which step you skipped, not that "something failed".
What you do not have to do
- Map zones. You send your zone and we resolve the portal's. If one is not mapped, the checker warns you before you publish.
- Keep track of the allowance. The portal reports it and we pass it on in the publish response.
- Look up the plans before each publication. If the one you asked for is not there, the response tells you which ones are.
- Retry with a different object when the portal rejects. Check first: it is free and tells you the same thing without spending.
Related
- Best practices — the six rules that apply to all the flows
- Publication — the portals and what changes on each
- Creating properties · Checking · Publishing