POST Contact/FinancingRequest

The ressource represents financing requests. Consumers can leave contact information and terms of financing. Financing requests are forwarded to random mortgage providers (based on a sophisticated algorithm).

http://rest.immobilienscout24.de/restapi/api/financing/construction/v2/contact/financingrequest

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

Body

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:financingRequest xmlns:ns2="http://rest.immobilienscout24.de/schema/financing/construction/2.0"
                        xmlns:ns3="http://rest.immobilienscout24.de/schema/financing/construction/1.0">
    <contactRequest>
        <financingTerms>
            <geoCode>1276003001046</geoCode>
            <amortizationRate>2.00</amortizationRate>
            <employment>EMPLOYED</employment>
            <fixedNominalInterestRate>FIFTEEN_YEARS</fixedNominalInterestRate>
            <financing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:BuildingFinancing">
                <purchasePrice>250000.00</purchasePrice>
                <ownFunds>50000.00</ownFunds>
                <additionalCosts>0.00</additionalCosts>
                <financingStart>IN_BETWEEN_THREE_AND_SIX_MONTHS</financingStart>
                <projectState>LAND_PROPERTY_AND_COMPANY_EXIST</projectState>
            </financing>
        </financingTerms>
        <contactAddress>
            <street>Meine Musterstraße</street>
            <streetNumber>123a</streetNumber>
            <postalCode>13507</postalCode>
            <location>Berlin</location>
        </contactAddress>
        <exposeId>1231231231</exposeId>
        <objectId>BAH-12a</objectId>
        <useType>OWNER_OCCUPATION</useType>
        <salutation>MR</salutation>
        <surname>Mustermann</surname>
        <forename>Max</forename>
        <email>max.mustermann@is24-test.de</email>
        <phoneNumber>030278687686</phoneNumber>
        <message>Guten Tag</message>
        <contactChannel>TELEPHONE</contactChannel>
        <availability>SIXTEEN_TO_NINETEEN</availability>
        <dateOfBirth>1990-10-01</dateOfBirth>
        <bank>Parkbank</bank>
        <numberOfBorrowers>2</numberOfBorrowers>
        <currentCredits>20000</currentCredits>
        <kfwPromotion>true</kfwPromotion>
    </contactRequest>
</ns3:financingRequest>

JSON

{
	"contactRequest": {
		"financingTerms": {
			"amortizationRate":2.00,
                        "geoCode" : "1276003001046",
			"employment":"EMPLOYED",
			"fixedNominalInterestRate":"FIFTEEN_YEARS",
			"financing":{
				"type":"BuildingFinancing",
				"purchasePrice":250000.00,
				"ownFunds":50000.00,
				"additionalCosts":0.00,
				"financingStart":"IN_BETWEEN_THREE_AND_SIX_MONTHS",
				"projectState":"LAND_PROPERTY_AND_COMPANY_EXIST"
			}
		},
                "useType": "OWNER_OCCUPATION",
		"salutation":"MR",
		"surname":"Mustermann",
		"forename":"Max",
		"email":"max.mustermann@is24-test.de",
		"phoneNumber":"030278687686",
		"message":"Guten Tag",
		"contactChannel":"TELEPHONE",
		"availability":"SIXTEEN_TO_NINETEEN",
                "contactAddress": {
                      "street": "Meine Musterstraße",
                      "streetNumber": "123a",
                      "postalCode": "13507",
                      "location": "Berlin"
                 }, 
                "exposeId": "123sad23",
                "objectId":"BAH-12a",
                "netIncome": 3500,
		"dateOfBirth":"2010-10-01",
		"bank": "Parkbank",
		"numberOfBorrowers": 2,
		"currentCredits": 20000,
		"kfwPromotion": true
	}
}

Mandatory fields are marked with *

 

contactRequest.financingTerms.geoCode* (Geo code of the search region(e.g. 1276003001046= Berlin-Mitte). When geo code is provider no postal code is needed)  

contactRequest.financingTerms.postalCode* (Postal code of the search region. When postal code is provider no geo code is needed)

contactRequest.financingTerms.amortizationRate* (Tilgung p.a. in %)

 

contactRequest.financingTerms.employment*:

  • CIVIL_SERVANT=Beamter
  • EMPLOYED=Angestellt
  • FREELANCER=Freiberufler
  • PENSIONER=Rentner
  • SELFEMPLOYED=Selbstständig
  • UNEMPLOYED=Arbeitssuchend

 

contactRequest.financingTerms.fixedNominalInterestRate* (Sollzinsbindung)

  • FIVE_YEARS=fünf Jahre
  • TEN_YEARS=zehn Jahre
  • FIFTEEN_YEARS=fünfzehn Jahre
  • TWENTY_YEARS=zwanzig Jahre

contactRequest.financingTerms.financing: This object covers the details of the financing.

There are three different types of finanancings. The type affects which fields can be set and which values the fields can have.

contactRequest.financingTerms.financing.type*

  • BuildingFinancing (Finanzierung eines Neubaus)
  • PurchaseFinancing (Finanzierung eines Kaufs)
  • FollowupFinancing (Anschlussfinanzierung)

 

financing.type = BuildingFinancing:

 

contactrequest.financingTerms.financing.purchasePrice* (Kaufpreis des Objektes)

contactrequest.financingTerms.financing.ownFunds* (Eigenkapital)

contactrequest.financingTerms.financing.additionalCosts* (Nebenkosten)

contactrequest.financingTerms.financing.financingStart* 

  • NA 
  • IN_LESS_THAN_THREE_MONTH=weniger als 3 Monate
  • IN_BETWEEN_THREE_AND_SIX_MONTHS=in 3 bis 6 Monaten
  • IN_MORE_THAN_SIX_MONTH=in mehr als 6 Monaten

contactrequest.financingTerms.financing.projectState*

  • NA 
  • NOT_YET_IN_PLANNING=noch nicht in Planung 
  • LAND_PROPERTY_EXISTS=Grundstück vorhanden 
  • LAND_PROPERTY_AND_COMPANY_EXIST=Grundstück und Haushersteller vorhanden

--------------------------------------------------------------------

 

financing.type = PurchaseFinancing

 

contactrequest.financingTerms.financing.purchasePrice* (Kaufpreis des Objektes)

contactrequest.financingTerms.financing.ownFunds* (Eigenkapital)

contactrequest.financingTerms.financing.additionalCosts* (Nebenkosten)

contactrequest.financingTerms.financing.financingStart* 

  • NA
  • IN_LESS_THAN_THREE_MONTH
  • IN_BETWEEN_THREE_AND_SIX_MONTHS
  • IN_MORE_THAN_SIX_MONTH

contactrequest.financingTerms.financing.projectState*

  • NA
  • REAL_ESTATE_VISITED=Objekt besichtigt
  • REAL_ESTATE_NOT_YET_VISITED=Objekt nicht besichtigt
  • PURCHASING_NEGOTIATIONS=In Kaufverhandlung

------------------------------------------------------------------------

 

financing.type=FollowupFinancing

 

contactrequest.financingTerms.financing.propertyValue*(Objektwert)

contactrequest.financingTerms.financing.remainingDebt* (Restschuld)

contactrequest.financingTerms.financing.financingStart*

  • NA
  • IN_LESS_THAN_ONE_YEAR=in weniger als 1 Jahr
  • IN_ONE_YEAR=in 1 Jahr
  • IN_TWO_YEARS=in 2 Jahren
  • IN_THREE_YEARS=in 3 Jahren
  • IN_FOUR_YEARS=in 4 Jahren
  • IN_FIVE_YEARS=in 5 Jahren

 

--------------------------------------------------------------------------

 

contactrequest.useType*

  • OWNER_OCCUPATION
  • PARTIALLY_RENTING
  • RENTING
  • UNKNOWN

 

contactRequest.salutation

  • MR = Herr
  • MRS = Frau
  • UNKNOWN = keine Angaben

 

contactRequest.surname* (Second name of the requester)

contactRequest.forename* (First name of the requester)

contactRequest.email* (Email address of the requester)

contactRequest.phoneNumber* (Phonenumber of the requester)

contactRequest.message (Message of the requester)

contactRequest.contactChannel*

  • TELEPHONE=Telefon
  • MEETING_AT_PROVIDERS_PLACE=Gespräch beim Anbieter (DEPRECATED)
  • MEETING_AT_REQUESTERS_PLACE=Hausbesuch (DEPRECATED)
  • EMAIL=Email (DEPRECATED)
  • UNKNOWN=keine Angaben (DEPRECATED)

contactRequest.availability (Erreichbarkeit)

  • ALL_DAY
  • EIGHT_TO_TWELVE
  • TWELVE_TO_SIXTEEN
  • SIXTEEN_TO_NINETEEN

contactRequest.netIncome (Netincome of the requester)

contactRequest.bank (the main bank of the requester)

contactRequest.dateOfBirth (the date of birth of the requester)

contactRequest.numberOfBorrowers (number of borrowers exists)

contactRequest.currentCredits (sum of running credits of the requester)

contactRequest.subscribeToNewsLetter (Subscribe to financing construction newsletters)

contactRequest.kfwPromotion (requester is interested in KfW consulting)

-------------------------------------------------------------------

 

Address of the requester:

contactRequest.contactAddress.street (Street of the requester)

contactRequest.contactAddress.streetNumber (Street number of the requester)

contactRequest.contactAddress.postalCode (PostalCode of the requester)

contactRequest.contactAddress.location (Location of the requester)

------------------------------------------------------------------

 

Expose Related fields:

contactRequest.exposeId (If contact request is related to an expose)

contactRequest.objectId (If contact request is related to an expose; it is the field realEstate.externalId returned by the ExposeAPI)

Validation

The resource returns a list of validation errors as shown below. Each message hasmessageCode and a message field. If the error is connected to a certain field in the request the message object has two additional fields: parameterName and reason.

  • parameterName: the path to field e.g. contactRequest.postalCode
  • reason: why is this field wrong
{
  "message": [{
    "messageCode": "ERROR_COMMON_SCHEMA_VALIDATION_FAILED",
    "message": "The request is not schema valid. [Invalid parameter: parameterName=contactAddress.postalCode reason=The request is not schema valid. [postal code does not exists]]",
    "parameterName": "contactAddress.postalCode",
    "reason": "Invalid parameter: parameterName=contactAddress.postalCode reason=The request is not schema valid. [postal code does not exists]"
  }]
}

Basic validation

All required fields described above are validated if they exist. Besides that all fields in the request body must have the correct type (date, string, number).

Enum validation

The following fields are matched to enum values. If the value can not be matched, a validation error is thrown with one of the follwing parameterNames:

  • contactRequest.contactChannel
  • contactRequest.salutation
  • contactRequest.useType
  • contactRequest.availability
  • contactRequest.financingTerms.employment
  • contactRequest.financingTerms.fixedNominalInterestRate
  • contactRequest.financingTerms.financing.projectState
  • contactRequest.financingTerms.financing.type
  • contactRequest.financingTerms.financing.financingStart

Location Validation

In the financingTerms object you need to provide either a valid geoCode or postalCode.

  • If geoCode is not 13 digits long or if it does not exist: parameterName=contactRequest.financingTerms.geoCode
  • If postalCode is no existing German postal code: parameterName=contactRequest.financingTerms.postalCode 
  • If both are missing: parameterName=location

Blacklisting

We do some blacklist checks for most of the String fields. If a blacklist error occurs it is stated in the reason field of the message object. (e.g. " ... [SURNAME is blacklisted]"). The parameterNaem contains the path of the field, as described above.

Address Validation

If you provide an address, it is validated the following way:

  • all fields are required
  • the postalCode must be an existing German postalCode

Phonenumber

parameterName=contactRequest.phoneNumber

The phone number must be a digit. Besides that we use some advanced phonenumber parsing. But if the phone number really exists, you should not worry. 

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
  • The requested operation was successful.