Add OnTop

This method provides a method 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}

Supported media types:
XML

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