GETbyID OnTop Placement

This method provides a method to get information about the OnTop Placement of a real estate.

https://rest.immobilienscout24.de/restapi/api/commercial-offer/v1.0/user/{username or me}/realestate/{id or externalId with prefix "ext-"}

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

Query Parameters

  • none
Body
  • GETbyID WITHOUT Body.
Example request

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

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 200 OK: The requested operation was successful.
  • Status 404 The requested real estate could not be found

 

Note:

The new commercial OTP products are based on points. Therefore with each response the available product catalog to use on this listing will be returned.
Example: if a listing has already a business product set, the only available option is to upgrade to a first product. Therefore only this information will be returned

Possible OnTop Placements:

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

This catalog contains also the point prices for the

  • Prio option in each OnTop placement and for the basic listing itself
  • Reservation option for firstplacement (element "available")

Header

No special headers.

Body

Example response I: the requested listing has a already a businessplacement with prio option placed. Therefore only an upgrade to firstplacement is possible. As the firstplacement is exlusively once available for the building of the listing, this will get market by the attribute "available". As in this case the firstplacement is not available, the reservation option is also returned, as it is possible to do a reservation for the upgrade.

<ontopplacement:ontopplacements 
xmlns:ontopplacement=
"http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
xmlns:xlink="http://www.w3.org/1999/xlink">
   <ontopplacement realestateid="53483572">
      <currentproduct name="businessplacement">
      	<options>
      		<option name="priority" />
      	</options>
      	<servicePeriod>
         <dateFrom>2014-01-28T13:17:10.000+01:00</dateFrom>
         <dateTo>2014-02-28T13:17:10.000+01:00</dateTo>
        </servicePeriod>
      </currentproduct>
      <productcatalog>
        <product name="firstplacement" available="false">
            <points>500</points>
            <options>
              <option name="priority">
              	<points>75</points>
              </option>
              <option name="enqueue">            
                <availableDate>2014-05-06</availableDate>
              	<points>30</points>
              </option>
            </options>   
        </product>
      </productcatalog>
      <remainingBalance>500</remainingBalance>
   </ontopplacement>
</ontopplacement:ontopplacements>

Example response II: the requested listing has no OnTop placement set. Therefore all OnTop placements are available. As the first placement is available, the reservation option is not given. Also a prio option on the basic listing is possible to set.

<ontopplacement:ontopplacements 
xmlns:ontopplacement=
"http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
xmlns:xlink="http://www.w3.org/1999/xlink">
   <ontopplacement realestateid="53483572">
      <currentproduct name="basic" />
      <productcatalog>
        <product name="firstplacement" available="true">
            <points>500</points>
            <options>
              <option name="priority">
              	<points>75</points>
              </option>
            </options>   
        </product>
        <product name="businessplacement">
            <points>300</points>
            <options>
              <option name="priority">
              	<points>50</points>
              </option>
            </options>   
        </product>
        <product name="basic">
            <points>0</points> 
            <options>
              <option name="priority">
              	<points>35</points>
              </option> 
           </options>
        </product>
      </productcatalog>
      <remainingBalance>500</remainingBalance>
   </ontopplacement>
</ontopplacement:ontopplacements>

Example response III: the requested listing has a already a firstplacement with prio option placed and two reservations. Therefore only an upgrade to firstplacement is possible. As the firstplacement is exlusively once available for the building of the listing, this will get market by the attribute "available". As in this case the firstplacement is not available, the reservation option is also returned, as it is possible to do another reservation.

<ontopplacement:ontopplacements 
xmlns:ontopplacement=
"http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
xmlns:xlink="http://www.w3.org/1999/xlink">
   <ontopplacement realestateid="53483572">
      <currentproduct name="firstplacement">
      	<options>
      		<option name="priority" />
                <option name="enqueue">            
                  <availableDate>2014-05-06</availableDate>
                </option>
                <option name="enqueue">            
                  <availableDate>2014-06-06</availableDate>
                </option>
      	</options>
      	<servicePeriod>
         <dateFrom>2014-01-28T13:17:10.000+01:00</dateFrom>
         <dateTo>2014-02-28T13:17:10.000+01:00</dateTo>
        </servicePeriod>
      </currentproduct>
      <productcatalog>
        <product name="firstplacement" available="false">
            <points>0</points>
            <options>
              <option name="priority">
              	<points>0</points>
              </option>
              <option name="enqueue">            
                <availableDate>2014-07-06</availableDate>
              	<points>30</points>
              </option>
            </options>   
        </product>
      </productcatalog>
      <remainingBalance>500</remainingBalance>
   </ontopplacement>
</ontopplacement:ontopplacements>

Example response IV: the requested listing has a already a businessplacement with prio option placed and one reservation for the first upgrade. As the firstplacement is exlusively once available for the building of the listing, this will get market by the attribute "available". As in this case the firstplacement is not available, the reservation option is also returned, as it is possible to do another reservation.

<ontopplacement:ontopplacements 
xmlns:ontopplacement="http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
xmlns:xlink="http://www.w3.org/1999/xlink">
    <ontopplacement realestateid="70663112">
        <currentproduct name="businessplacement">
            <options>
                <option name="priority"/>
                <option name="enqueued">
                    <availableDate>2018-08-04</availableDate>
                </option>
            </options>
            <servicePeriod>
                <dateFrom>2018-06-26T11:31:14.933205+02:00</dateFrom>
                <dateTo>2018-07-26T11:31:14.933205+02:00</dateTo>
            </servicePeriod>
        </currentproduct>
        <productcatalog>
            <product name="firstplacement" available="false">
                <points>0</points>
                <options>
                    <option name="priority">
                        <points>0</points>
                    </option>
                    <option name="enqueue">
                        <points>20</points>
                    </option>
                </options>
            </product>
        </productcatalog>
        <remainingBalance>15160</remainingBalance>
    </ontopplacement>
</ontopplacement:ontopplacements>

Example for unsuccessful response (404):

<ontopplacement:ontopplacements 
xmlns:ontopplacement=
"http://rest.immobilienscout24.de/schema/commercial-offer/ontopplacement/1.0" 
xmlns:xlink="http://www.w3.org/1999/xlink">
   <ontopplacement realestateid="53483572">
      <messageCode>ERROR_REQUESTED_DATA_NOT_FOUND</messageCode>
      <message>Real estate with id='53483572' not found</message>
   </ontopplacement>
</ontopplacement:ontopplacements>