Add OnTop
This method provides a way to add an OnTop Placement to your real estates by ID. Only one type of OnTop placements (first OR business) can be set per real estate.
POST /commercial-offer/v1.0/user/{username or me}/realestate/{id or externalId with prefix "ext-"}/ontop/{ontop placement}
Possible OnTop Placements:
- firstplacement ("First-Platzierung")
- businessplacement ("Business-Platzierung")
Request
Path Parameters
| PARAMETER | DESCRIPTION |
|---|---|
| Username | the username which the user uses for logging in to www.immobilienscout24 |
| me | "me" can be used instead of the username, when the user is logged in by 3-legged oauth |
| id | the unique scout object ID, which is being created by POST REALESTATE automatically |
| external-id | can be used instead of the scout object ID. it is the customer-defined ID of the real estate, must be unique per user |
| ontop placement | the type of the OnTop placement (firstplacement or businessplacement) |
Example
This request will create "businessplacement" for object id 70631302 without body
https://rest.immobilienscout24.de/restapi/api/commercial-offer/v1.0/user/me/realestate/70631302/ontop/businessplacement
Response
- Status 201, new top placement has bin successfully created
-
Status 412, this status is returned if:
-
the real estate is not published
- the real estate has already a OnTop placement
- if you are not allowed to do OnTop placement
- have enough contingent to book more OnTop placements
please note: The commercial real estate types are getting grouped into buildings bases on their given address/location. The firstplacement ("First-Platzierung") is an exclusive product that can be only booked once for a specific address/location. If a real estate is grouped into a building, that already has a firstplacement", an error message with a status of 412 will be returned.
Prio Option
With the priority option you can upgrade the available commercial OnTop products and even the basic placement to have a priority option ("Prio-Option"), which affects the ordering of the real estates. The priority option can applied in two scenarios: - as an attribute together with a OnTop product placement - independent as a resource for a basic listing
Possible OnTop Placements for priority option:
- firstplacement ("First-Platzierung")
- businessplacement ("Business-Platzierung")
Request with OnTop placement
without body
https://rest.immobilienscout24.de/restapi/api/commercial-offer/v1.0/user/{username or me}/realestate/{id or externalId}/ontop/{ontop placement}/priority
Request with basic listing
without body
https://rest.immobilienscout24.de/restapi/api/commercial-offer/v1.0/user/{username or me}/realestate/{id or externalId}/ontop/basic/priority
"Waiting list" option for first placement
The commercial real estate types are getting grouped into buildings based on their given address/location. The firstplacement ("First-Platzierung") is an exclusive product that can be only booked once for a specific address/location.
If a real estate is grouped into a building, that already has a firstplacement", an error message with a status of 412 will be returned.
Therefore, an "enqueue"("Warteliste") option is available for the firstplacement. This option can be used only, if the building has already a firstplacement. A succesful reservation will queue the requester into to be next for getting the firstplacement.
Please note: even if you are already having the firstplacement booked on your listing, you still can enqueue yourself to keep it or have it later again available. You can also do this multiple times, to be multiple times in the "waiting queue".
A reservation cannot be done together with the prio option, but the first can be afterwards upgraded, if it is in place.
Request
without body
POST https://rest.immobilienscout24.de/restapi/api/commercial-offer/v1.0/user/{username or me}/realestate/{id or externalId}/ontop/firstplacement/enqueue