POSTbyID OnTop Placement

This method provides a method to add an OnTop Placement to your real estates by ID.

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

Possible OnTop Placements:

  • showcaseplacement ("Schaufenster-Platzierung")
  • premiumplacement ("Premium-Platzierung")
  • topplacement ("Top-Platzierung")

Supported media types

  • XML (Accept: application/xml)
  • JSON (Accept: application/json)

Authorization requirements

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

Please use a secure connection (https) 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 (showcaseplacement, premiumplacement or topplacement)

Query Parameters

  • none

Body

  • POSTbyID PremiumPlacement WITHOUT Body.

Query Parameters

  • none

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 or the real estate has already a premium placement or if you are not allowed to book one more premium placement.

Header

No special headers.

Body

XML

<common:messages xmlns:ns2="http://rest.immobilienscout24.de/schema/platform/gis/1.0" xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
   <message>
      <messageCode>MESSAGE_RESOURCE_CREATED</messageCode>
      <message>Resource [premiumplacement] with id [] has been created.</message>
   </message>
</common:messages>

or 412 (real estate not published):

<common:messages xmlns:ns2="http://rest.immobilienscout24.de/schema/platform/gis/1.0" xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
   <message>
      <messageCode>ERROR_RESOURCE_VALIDATION</messageCode>
      <message>Error while validating input for the resource. [MESSAGE: premiumplacement for this real estate is not possible:Not allowed to perform ontop for unpublished realestate (#70631302).]</message>
   </message>
</common:messages>

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

<common:messages xmlns:ns2="http://rest.immobilienscout24.de/schema/platform/gis/1.0" xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
   <message>
      <messageCode>ERROR_RESOURCE_VALIDATION</messageCode>
      <message>Error while validating input for the resource. [MESSAGE: real estate with id='70631302' already has a premium placement.]</message>
   </message>
</common:messages>

or 412 (not allowed to book one more premium placement):

<common:messages xmlns:ns2="http://rest.immobilienscout24.de/schema/platform/gis/1.0" xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
   <message>
      <messageCode>ERROR_RESOURCE_VALIDATION</messageCode>
      <message>Error while validating input for the resource. [MESSAGE: premiumplacement for this real estate is not possible:No tally found to ontop realestate(#70631303).]</message>
   </message>
</common:messages>