Skip to content

Financing Request

The resource 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).

POST /financing/construction/v2/contact/financingrequest

Supported media types:
XML
JSON

Request

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
    }
}

Body parameters


PARAMETER DESCRIPTION MANDATORY
contactRequest.financingTerms .geoCode Geo code of the search region(e.g. 1276003001046= Berlin-Mitte). When geo code is provider no postal code is needed yes
contactRequest.financingTerms .postalCode Postal code of the search region. When postal code is provider no geo code is needed yes
contactRequest.financingTerms .amortizationRate Tilgung p.a. in % yes
contactRequest.financingTerms .employment CIVIL_SERVANT, EMPLOYED, FREELANCER, PENSIONER, SELFEMPLOYED, UNEMPLOYED, WORKER, HOUSEWIFE
German translation (same order as above): Beamter, Angestellt, Freiberufler, Rentner, Selbstständig, Arbeitssuchend, Arbeiter/in, Hausfrau/mann
yes
contactRequest.financingTerms .fixedNominalInterestRate FIVE_YEARS, TEN_YEARS, FIFTEEN_YEARS, TWENTY_YEARS yes
contactRequest.financingTerms .financing This object covers the details of the financing no
contactRequest.financingTerms .financing.type BuildingFinancing (Finanzierung eines Neubaus), PurchaseFinancing (Finanzierung eines Kaufs), FollowupFinancing (Anschlussfinanzierung) for further information on FinancingType. yes
contactrequest.useType OWNER_OCCUPATION, PARTIALLY_RENTING, RENTING, UNKNOWN yes
contactRequest.salutation MR, MRS, UNKNOWN no
contactRequest.surname Second name of the requester yes
contactRequest.forename First name of the requester yes
contactRequest.email Email address of the requester yes
contactRequest.phoneNumber Phonenumber of the requester yes
contactRequest.message Message of the requester no
contactRequest.contactChannel TELEPHONE yes
contactRequest.availability ALL_DAY, EIGHT_TO_TWELVE, TWELVE_TO_SIXTEEN, SIXTEEN_TO_NINETEEN no
contactRequest.netIncome BELOW_500, OVER_500_UPTO_1000, OVER_1000_UPTO_1500, OVER_1500_UPTO_2000, OVER_2000_UPTO_2500, OVER_2500_UPTO_3000, OVER_2000_UPTO_3000, OVER_3000_UPTO_3500, OVER_3500_UPTO_4000, OVER_3000_UPTO_4000 no
contactRequest.bank the main bank of the requester no
contactRequest.dateOfBirth the date of birth of the requester no
contactRequest.numberOf Borrowers number of borrowers exists no
contactRequest.currentCredits sum of running credits of the requester no
contactRequest.subscribeTo NewsLetter Subscribe to financing construction newsletters no
contactRequest.kfwPromotion requester is interested in KfW consulting no
Address of the requester:
contactRequest.contactAddress .street Street of the requester no
contactRequest.contactAddress .streetNumber Street number of the requester no
contactRequest.contactAddress .postalCode PostalCode of the requester no
contactRequest.contactAddress .location Location of the requester no
Expose Related fields:
contactRequest.exposeId If contact request is related to an expose no
contactRequest.objectId If contact request is related to an expose; it is the field realEstate.externalId returned by the ExposeAPI no


Financing types

financing.type = BuildingFinancing:

PARAMETER VALUE MANDATORY
contactrequest.financingTerms .financing.purchasePrice purchase price of the object yes
contactrequest.financingTerms .financing.ownFunds equity capital yes
contactrequest.financingTerms .financing.additionalCosts side costs yes
contactrequest.financingTerms .financing.financingStart NA, IN_LESS_THAN_THREE_MONTH, IN_BETWEEN_THREE_AND_SIX_ MONTHS, IN_MORE_THAN_SIX_MONTH yes
contactrequest.financingTerms .financing.projectState NA, NOT_YET_IN_PLANNING, LAND_PROPERTY_EXISTS, LAND_PROPERTY_AND_COMPANY_ EXIST, PROPERTY_FOUND, NOTARY_APPOINTMENT_PLANNED, ON_BUILDER_SEARCH yes

financing.type = PurchaseFinancing:


PARAMETER VALUE MANDATORY
contactrequest.financingTerms .financing.purchasePrice purchase prise of the object yes
contactrequest.financingTerms .financing.ownFunds equity capital yes
contactrequest.financingTerms .financing.additionalCosts side costs yes
contactrequest.financingTerms .financing.financingStart NA, IN_LESS_THAN_THREE_MONTH, IN_BETWEEN_THREE_AND_SIX_ MONTHS, IN_MORE_THAN_SIX_MONTH yes
contactrequest.financingTerms .financing.projectState NA, NOT_YET_IN_PLANNING, LAND_PROPERTY_EXISTS, LAND_PROPERTY_AND_COMPANY_ EXIST, PROPERTY_FOUND, NOTARY_APPOINTMENT_PLANNED, ON_OBJECT_SEARCH yes

financing.type=FollowupFinancing:


PARAMETER VALUE MANDATORY
contactrequest.financingTerms .financing.propertyValue property value yes
contactrequest.financingTerms .financing.remainingDebt remaining debts yes
contactrequest.financingTerms .financing.financingStart NA, IN_LESS_THAN_ONE_YEAR, IN_ONE_YEAR, IN_TWO_YEARS, IN_THREE_YEARS, IN_FOUR_YEARS, IN_FIVE_YEARS yes


Validation

The resource returns a list of validation errors as shown below. Each message has messageCode 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.