BETA

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

PUT …/publication/{portal}.

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 youCost
GET /properties/{paId}what we recorded about that publicationfree
GET …/publication/{portal}what the portal says: whether it is online, its URL, the views1 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 youWhat you do
it is chosen hereread → decide → PUT, as below
it is chosen when publishingback to step 3: it travels with the publication, and the GET tells you in which field
the portal does not charge for itnothing: there is no position to buy

When it is chosen here, the order is read, decide, assign — never assign blind:

  1. The GET tells 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.
  2. You decide (or your user does). We do not choose for them.
  3. The PUT applies 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 recordthe error says the client needs declaring, and how
publish before their account is connectedthe error says that account needs connecting, with the portal named
publish a property you never loadedwe 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.