Skip to content

Appointment request

The resource represents appointment requests. Consumers can contact given mortgage providers with specified terms of financing.

POST /financing/construction/v2/contact/appointmentrequest

Supported media types:
XML
JSON

Request

XML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:appointmentRequest 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>123123123</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>
        <primaryAppointmentDate>1461708000000</primaryAppointmentDate>
        <primaryAppointmentTime>SIXTEEN_UNTIL_SEVENTEEN</primaryAppointmentTime>
        <secondaryAppointmentDate>1461708000000</secondaryAppointmentDate>
        <secondaryAppointmentTime>SEVENTEEN_UNTIL_EIGHTEEN</secondaryAppointmentTime>
        <dateOfBirth>1990-10-01</dateOfBirth>
        <bank>Parkbank</bank>
        <numberOfBorrowers>2</numberOfBorrowers>
        <currentCredits>20000</currentCredits>
        <kfwPromotion>true</kfwPromotion>
        <dpaAccepted>false</dpaAccepted>
        <title>NO_TITLE</title>
    </contactRequest>
    <referredOffers>
        <referredOffer>
            <providerId>111111</providerId>
            <product>DEFAULT</product>
        </referredOffer>
    </referredOffers>
</ns3:appointmentRequest>

JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
   "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",
      "primaryAppointmentDate":1461708000000,
      "primaryAppointmentTime":"SIXTEEN_UNTIL_SEVENTEEN",
      "secondaryAppointmentDate":1461708000000,
      "secondaryAppointmentTime":"SEVENTEEN_UNTIL_EIGHTEEN",
      "kfwPromotion":true,
      "dpaAccepted":false,
      "title":"NO_TITLE",
      "contactAddress":{
         "street":"Meine Musterstraße",
         "streetNumber":"123a",
         "postalCode":"13507",
         "location":"Berlin"
      },
      "exposeId":213123123,
      "objectId":"BAH-12a",
      "netIncome":3500,
      "dateOfBirth":"2010-10-01",
      "bank":"Parkbank",
      "numberOfBorrowers":2,
      "currentCredits":20000
   },
   "referredOffers":[
      {
         "providerId":111111,
         "product":"DEFAULT"
      }
   ]
}

Body parameters

PARAMETER DESCRIPTION MANDATORY
referredOffers[].providerId Id of the mortgage provider to contact yes
referredOffers[].product The product you used in the search. Possible values: VIA, DEFAULT no
contactRequest.financingTerms .geoCode Geo code of the search region (e.g. 1276003001046 = Berlin-Mitte). When geo code is provided no postal code is needed yes
contactRequest.financingTerms .postalCode Postal code of the search region. When postal code is provided 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 .employmentSector MEDICAL no
contactRequest.financingTerms .fixedNominalInterestRate FIVE_YEARS, TEN_YEARS, FIFTEEN_YEARS, TWENTY_YEARS, THIRTY_YEARS, FORTY_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, MEETING_AT_PROVIDERS_PLACE, MEETING_AT_REQUESTERS_PLACE, EMAIL, UNKNOWN yes
**Appointment** An appointment consists of the Date field which is a Unix Timestamp and a time field which is an enum described below. Please make sure to either submit both values or none. It is possible to set a primary and a secondary appointment
contactRequest .primaryAppointmentDate Primary date in miliseconds of prefered appointment no
contactRequest .secondaryAppointmentDate Secondary date in miliseconds of prefered appointment no
contactRequest .primaryAppointmentTime
/
contactRequest .secondaryAppointmentTime		 ALL_DAY, EIGHT_TO_TWELVE, TWELVE_TO_SIXTEEN, SIXTEEN_TO_NINETEEN, UNKNOWN, TEN_UNTIL_ELEVEN, ELEVEN_UNTIL_TWELVE, TWELVE_UNTIL_THIRTEEN, THIRTEEN_UNTIL_FOURTEEN, FOURTEEN_UNTIL_FIFTEEN, FIFTEEN_UNTIL_SIXTEEN, SIXTEEN_UNTIL_SEVENTEEN, SEVENTEEN_UNTIL_EIGHTEEN, EIGHTEEN_UNTIL_NINETEEN, NINETEEN_UNTIL_TWENTY, TWENTY_UNTIL_TWENTYONE no
contactRequest.netIncome Net income of the requester no
contactRequest.bank the main bank of the requester no
contactRequest.dateOfBirth the date of birth of the requester no
contactRequest.numberOfBorrowers number of borrowers exists no
contactRequest.currentCredits sum of running credits of the requester no
contactRequest.kfwPromotion requester is interested in KfW consulting no
contactRequest.dpaAccepted Accepted the Data Processing Agreement no
**Address of the requester:**
contactRequest.contactAddress .street Street of the requester yes
contactRequest.contactAddress .streetNumber Street number of the requester yes
contactRequest.contactAddress .postalCode PostalCode of the requester yes
contactRequest.contactAddress .location Location of the requester yes
**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
contactRequest.title NO_TITLE, DOCTOR, PROFESSOR, PROFESSOR_DOCTOR 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, REAL_ESTATE_VISITED, REAL_ESTATE_NOT_YET_VISITED, PURCHASING_NEGOTIATIONS, OBJECT_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 
    1
2
3
4
5
6
7
8
    {
  "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.primaryAppointmentTime
  • contactRequest.secondaryAppointmentTime
  • contactRequest.financingTerms.employment
  • contactRequest.financingTerms.employmentSector
  • contactRequest.financingTerms.fixedNominalInterestRate
  • contactRequest.financingTerms.financing.projectState
  • contactRequest.financingTerms.financing.type
  • contactRequest.financingTerms.financing.financingStart
  • contactRequest.title
  • referredOffers[].product

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 parameterName contains the path of the field, as described above.

Appointment dates and times It is optional to provide appointment details, but if you provide them they are validated with the following rules:

  • the date field must contain a valid unix timestamp > 0
  • the time field must match to one of the enum values (see above in the request body section)
  • you have to provide the date and the time field (it is not allowed to set primaryAppointmentTime without setting primaryAppointmentDate ...)

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.