POSTbyID OnTop Placement

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.

https://rest.immobilienscout24.de/restapi/api/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")

Supported media types

  • XML (Accept: application/xml)

Authorization requirements

A System Key and an authenticated user are required for this operation:

Request

Path Parameters

  • Username: the username which the user uses for logging in to www.immobilienscout24.
  • Username: "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)

Query Parameters

  • none

Body

  • POSTbyID OnTopPlacement WITHOUT Body.

Query Parameters

  • none
Example request

https://rest.immobilienscout24.de/restapi/api/commercial-offer/v1.0/user/me/realestate/70631302/ontop/businessplacement

Response

The following section includes the HTTP status code, a short description and examples for the response body content of a successful processed request.
Error responses as well as other simple message responses are described in detail within the common message responses.

  • Status 201 Created

This status code is returned after a new entity of a resource was successfully created.

  • Status 412

This status code 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 notice:

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.

Header

No special headers.

Body

<ontopplacement:ontopplacements 
  xmlns:ontopplacement=
    "http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
    <ontopplacement realestateid="70631302">
        <messageCode>MESSAGE_RESOURCE_CREATED</messageCode>
        <message>Real estate with id '70631302' has been BUSINESS placed.</message>
    </ontopplacement>
</ontopplacement:ontopplacements>

or 412 (real estate not published):

<ontopplacement:ontopplacements 
  xmlns:ontopplacement=
    "http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
    <ontopplacement realestateid="70631302">
        <messageCode>ERROR_RESOURCE_VALIDATION</messageCode>
      <message>BUSINESS placement for real estate with id='70631302' is not possible. 
Not allowed to perform ontop placements for unpublished real estates.</message>
    </ontopplacement>
</ontopplacement:ontopplacements>

or 412 (real estate has already a business placement):

<ontopplacement:ontopplacements 
  xmlns:ontopplacement=
    "http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
    <ontopplacement realestateid="70631302">
        <messageCode>ERROR_RESOURCE_VALIDATION</messageCode>
        <message>Real estate with id='70631302' already has a BUSINESS placement.</message>
    </ontopplacement>
</ontopplacement:ontopplacements>

or 412 (not able to book one more business placement due to contingent limitation):

<ontopplacement:ontopplacements 
  xmlns:ontopplacement=
    "http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
    <ontopplacement realestateid="70631303">
        <messageCode>ERROR_RESOURCE_VALIDATION</messageCode>
        <message>BUSINESS placement for real estate with id='70631303' is not possible: 
contingent has only 75 points available, BUSINESS placement needs100s points.</message>
    </ontopplacement>
</ontopplacement:ontopplacements>

or 412 (the building the listing is grouped in already has a firstplacements):

<ontopplacement:ontopplacements 
  xmlns:ontopplacement=
    "http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
    <ontopplacement realestateid="70631302">
        <messageCode>ERROR_RESOURCE_VALIDATION</messageCode>
      <message>First placement for real estate with id='70631302' is not 
possible: building of real estate already has a first placement.</message>
    </ontopplacement>
</ontopplacement:ontopplacements>

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

 

Available OnTop placements for priority option

  • firstplacement ("First-Platzierung")
  • businessplacement ("Business-Platzierung")

With OnTop Placement

Request

https://rest.immobilienscout24.de/restapi/api/commercial-offer/v1.0/user/{username or me}/realestate/{id or externalId}/ontop/{ontop placement}/priority

Path Parameters

  • Username: the username which the user uses for logging in to www.immobilienscout24.
  • Username: "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)
  • priority: adding the prio option to the ontop placement

Query Parameters

  • none
Body
  • POSTbyID OnTopPlacement WITHOUT Body.
Response
<ontopplacement:ontopplacements 
  xmlns:ontopplacement=
    "http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
    <ontopplacement realestateid="70631302">
        <messageCode>MESSAGE_RESOURCE_CREATED</messageCode>
        <message>Real estate with id '70631302' has been 
BUSINESS with prio option placed.</message>
    </ontopplacement>
</ontopplacement:ontopplacements>

With basic listing

https://rest.immobilienscout24.de/restapi/api/commercial-offer/v1.0/user/{username or me}/realestate/{id or externalId}/ontop/basic/priority

Request

Path Parameters

  • Username: the username which the user uses for logging in to www.immobilienscout24.
  • Username: "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
  • priority: adding the prio option to the basic listing

Query Parameters

  • none
Body
  • POSTbyID OnTopPlacement WITHOUT Body.
Response

The following section includes the HTTP status code, a short description and examples for the response body content of a successful processed request.
Error responses as well as other simple message responses are described in detail within the common message responses.

  • Status 201 Created

This status code is returned after a new entity of a resource was successfully created.

  • Status 412

This status code is returned, if

  • the real estate is not published
  • the real estate has already a ontop placement or a prio option
  • if you are not allowed to use the prio option
  • have enough contingent to book more prio options for basic listings

Body

<ontopplacement:ontopplacements 
  xmlns:ontopplacement=
    "http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
    <ontopplacement realestateid="70631302">
        <messageCode>MESSAGE_RESOURCE_CREATED</messageCode>
      <message>Real estate with id '70631302' has been 
BASIC with prio option placed.</message>
    </ontopplacement>
</ontopplacement:ontopplacements>

"Waiting list" option for first placement

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.

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

POST https://rest.immobilienscout24.de/restapi/api/commercial-offer/v1.0/user/{username or me}/realestate/{id or externalId}/ontop/firstplacement/enqueue

Path Parameters

  • Username: the username which the user uses for logging in to www.immobilienscout24.
  • Username: "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: firstplacement is the only available option combined with the enqueue option
  • prio option (OPTIONAL): add to the firstplacement the prio option
  • enqueue: enqueue yourself into the waiting list for this building

Query Parameters

  • none
Body
  • POSTbyID OnTopPlacement WITHOUT Body.
Response

Please note: the response will not contain the exptected latest date of the reservation, but this information is then returned in the GetByID response as part of the current product. See the documentation there with a response example.

<ontopplacement:ontopplacements 
  xmlns:ontopplacement=
    "http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
    <ontopplacement realestateid="70631302">
        <messageCode>MESSAGE_RESOURCE_CREATED</messageCode>
      <message>Real estate with id='70631302' has 
been enqueued for first placement.</message>
    </ontopplacement>
</ontopplacement:ontopplacements>

or 412 (the building the listing is grouped in has not a firstplacement):

<ontopplacement:ontopplacements 
  xmlns:ontopplacement=
    "http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
    <ontopplacement realestateid="70631302">
        <messageCode>ERROR_RESOURCE_VALIDATION</messageCode>
        <message>Enqueue option for this real estate not available: 
building of real estate with id='70631302' has not a first placement yet.</message>
    </ontopplacement>
</ontopplacement:ontopplacements>