GET Single Offer V3

Returns a list of resources identified by the following URL. The GET method of the single-offer resource is used to retrieve a construction financing offer for a certain mortgage provider according to the given financing terms query parameters.

Important: The PAngBV (Preisangabenverordnung) requires that you need to provide the following data when displaying an offer: effective and nominal interest rates, monthly rate, remaining debt after fixed interest termination (Ablauf der Sollzinsbindung), number of repayment rates, duration until repayment is complete and the total amount paid. You may only use this API if you display all this data. 

http://rest.immobilienscout24.de/restapi/api/financing/construction/v3/offer/single

Supported media types

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

Authorization requirements

  • At least a System Key is required for this operation. See Authentication via Two-legged OAuth for further details.

Request

Path Parameters

  • none

Query Paramters

required:

  • geocode - GeoCode of the search region
  • postalcode - the usage of geocode is preferred, usage of postalcode leadsto bad quality of the search results 

!!! you have to provide either a geocode or a postalcode

 

additional filter criteria:

  • provider - ID of the mortgage provider you want to get an offer from; if ommitted, the resource only returns the marketdata
  • financingtype - financing type; default: "PROPERTY_PURCHASE"
  • additionalCosts - additional costs; default: 0
  • ownfunds - own funds of the buyer; default: 50000
  • purchaseprice - purchase price of the project; default: 200000
  • remainingDebt - the remaining debt (followup financing); default: 100000
  • propertyValue - the value of the property (followup financing) default: 200000
 
  • amortizationrate - amortization rate; default: 2
  • employment - employment of the buyer; default: "EMPLOYED"
  • fixednominalinterestrate - fixed nominal interest rate; default: "TEN_YEARS"
 
There are three possible financingTypes:
  • PROPERTY_PURCHASE (Objektkauf)
  • BUILDING_FINANCING (Neubau)
  • FOLLOWUP_FINANCING (Anschlussfinanzierung)
 
If you search for followup financings, you need to provide remainingDebt and propertyValue instead of purchasePrice, additionalCosts and ownFunds. 
 
Possible employments:
  • CIVIL_SERVANT=Beamter
  • EMPLOYED=Angestellt
  • FREELANCER=Freiberufler
  • PENSIONER=Rentner
  • SELFEMPLOYED=Selbstständig
  • UNEMPLOYED=Arbeitssuchend

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 412: if providing wrong parameters

Header

No special headers.

Body

An offer allways contains a provider. The field distanceToSearchLocation contains the distance of the provider to the search location defined by the geoCode or the postalCode. This field might not always be present.

If interest rates are found then the offer has an amortizationData object. This includes information like the remaining debt after the fixed interest rates termination, the number of monthly rates until the loan is repayed as well as the total repayment. The lastModified field contains the timestamp when the interest rates of the given provider were updated.

Fields:

The minimum response consists of the fields offersFound and offer, where offer is an empty Array. This happens, if neither a concrete offer nor the average marketdata was found.

  • offer.amortizationData: if this object exists, all its attributes will be set
  • distanceToSearchLocation: optional
  • mortgageProvider: these fields will alway be set: id, name, logo, profileImage, numberOfRatings, averageRating
  • marketData: if present, all fields should be given as well
  • mortgageProvider.logo: comes in two different sizes: url and url120x90
  • mortgageProvider.profileImage: access via url

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:offers xmlns:ns2="http://www.w3.org/1999/xlink" xmlns:ns3="http://rest.immobilienscout24.de/schema/financing/construction/1.0">
  <offersFound>1</offersFound>
  <offer>
    <amortizationData>
      <effectiveInterestRate>2.51</effectiveInterestRate>
      <nominalInterestRate>2.18</nominalInterestRate>
      <monthlyRate>399</monthlyRate>
      <remainingDebt>143413</remainingDebt>
      <totalAmountPaid>243005</totalAmountPaid>
      <numberOfRates>255</numberOfRates>
      <lastModified>1458031579000</lastModified>
    </amortizationData>
    <distanceToSearchLocation>1.2</distanceToSearchLocation>
    <mortgageProvider id="111111" ns2:href="http://rest.immobilienscout24.de/restapi/api/financing/construction/v1.0/provider/111111">
      <name>The financing partner</name>
      <logo id="222222" ns2:href="http://rest.immobilienscout24.de/restapi/api/financing/construction/v1.0/providerlogo/222222">
        <url>http://www.immobilienscout24.de/baufinanzierung/app/mortgageProvider/222222/80x60/logo.png</url>
        <url120x90>http://www.immobilienscout24.de/baufinanzierung/app/mortgageProvider/222222/120x90/logo.png</url120x90>
      </logo>
      <profileImage id="333333" ns2:href="http://rest.immobilienscout24.de/restapi/api/financing/construction/v1.0/profile/222222">
        <url>http://www.immobilienscout24.de/baufinanzierung/app/mortgageProvider/222222/1/logo.png</url>
      </logo>
      <numberOfRatings>500</numberOfRatings>
      <averageRating>4.5</averageRating>
      <contactAddressRequired>true</contactAddressRequired>
    </mortgageProvider>
  </offer>
  <marketData>
    <averageInterestRate>2.30</averageInterestRate>
    <minInterestRate>2.30</minInterestRate>
    <maxInterestRate>2.30</maxInterestRate>
    <effectiveInterestRate>2.32</effectiveInterestRate>
  </marketData>
</ns3:offers>

JSON

{
  "offersFound": 1,
  "offer": [{
    "amortizationData": {
      "effectiveInterestRate": 2.51,
      "nominalInterestRate": 2.18,
      "monthlyRate": 399,
      "remainingDebt": 143413,
      "totalAmountPaid": 243005,
      "numberOfRates": 255,
      "lastModified": 1458031579000
    },
    "distanceToSearchLocation": 1.2,
    "mortgageProvider": {
      "id": 111111,
      "href": "http://rest.immobilienscout24.de/restapi/api/financing/construction/v1.0/provider/111111",
      "name": "The financing partner",
      "logo": {
        "id": 222222,
        "xLink": "http://rest.immobilienscout24.de/restapi/api/financing/construction/v1.0/providerlogo/222222",
        "url": "http://www.immobilienscout24.de/baufinanzierung/app/mortgageProvider/222222/80x60/logo.png",
        "url120x90": "http://www.immobilienscout24.de/baufinanzierung/app/mortgageProvider/222222/120x90/logo.png"
      },
      "profileImage": {
        "id": 333333,
        "xLink": "http://rest.immobilienscout24.de/restapi/api/financing/construction/v1.0/providerlogo/33333",
        "url": "http://www.immobilienscout24.de/baufinanzierung/app/mortgageProvider/3333333/1/logo.png"
      },
      "numberOfRatings": 500,
      "averageRating": 4.5,
      "contactAddressRequired": true
    }
  }],
  "marketData": {
    "averageInterestRate": 2.30,
    "minInterestRate": 2.30,
    "maxInterestRate": 2.30,
    "effectiveInterestRate": 2.32
  }
}