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 · take it down DELETE …/publication/{portal}
Steps 1 and 3 are the mandatory ones. Step 2 is free and saves you calls; 4, 5 and 6 are as needed.
1 · Load the property
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.
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.
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.
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.
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.
6 · 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 four rules that apply to all the flows
- Publication — the portals and what changes on each
- Creating properties · Checking · Publishing