Expose API

Contact

The resource contactform represents a contact request for a real estate. The contactform can be used to send a contact request to a realtor of an real estate.

https://rest.immobilienscout24.de/restapi/api/search/v1.0/expose/{expose_id}/contact

 

Note: A contact request could only processed if the realtor provides an email. If not, the expose contact form type NONE is set.

 

Supported methods

Contact/POST

The POST method of this sub-resource sends a contact request to the realtor of a real estate.

https://rest.immobilienscout24.de/restapi/api/search/v1.0/expose/{expose_id}/contact

 

Note:

  • Please specify only one contact form per call. This call sends only a contact request to the realtor, thus this request doesn't return a location header cause no resource was created.
  • You must provide the following HTTP headers:
    • - Accept: application/json or application/xml
    • - Content-Type: application/json or application/xml

Preparation

The client application has to load the expose via the Expose API to get the information about mandatory and optional fields. It can be retrieved from the contactFormConfiguration node in the response of the expose request.

Example (XML):

<contactFormConfiguration>
  <moveInDateField>MANDATORY</moveInDateField>
  <petsInHouseholdField>MANDATORY</petsInHouseholdField>        
  <numberOfPersonsField>MANDATORY</numberOfPersonsField>
  <employmentRelationshipField>MANDATORY</employmentRelationshipField>
  <incomeField>MANDATORY</incomeField>
  <firstnameField>MANDATORY</firstnameField>
  <lastnameField>MANDATORY</lastnameField>
  <phoneNumberField>MANDATORY</phoneNumberField>
  <emailAddressField>MANDATORY</emailAddressField>
  <addressField>MANDATORY</addressField>
  <applicationPackageCompletedField>MANDATORY</applicationPackageCompletedField>
  <salutationField>MANDATORY</salutationField>
  <messageField>OPTIONAL</messageField>
</contactFormConfiguration>

Example (JSON):

"contactFormConfiguration":{
  "moveInDateField":"MANDATORY",
  "petsInHouseholdField":"MANDATORY",
  "numberOfPersonsField":"MANDATORY",
  "employmentRelationshipField":"MANDATORY",
  "incomeField":"MANDATORY",
  "firstnameField":"MANDATORY",
  "lastnameField":"MANDATORY",
  "phoneNumberField":"MANDATORY",
  "emailAddressField":"MANDATORY",
  "addressField":"MANDATORY",
  "applicationPackageCompletedField":"MANDATORY",
  "salutationField":"MANDATORY",
  "messageField":"OPTIONAL"
}

 

The client application must ensure that the MANDATORY fields are part of the POST call to send the form (user/system has to enter the required data) - this is currently not verified by the RestAPI server to ensure backward compability with older client applications. However server-side validation could start at any time.

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

expose_id

    The Id of an expose to perform a contact request for.

Body

The content of the fields is not filtered (e.g. for cross-side scripting or cross-side request forgery).

The order of the fields is defined by the Schema. This is the order of all eventually possible fields (as defined by the Schema; not all fields can be used for every form, this depends on the form configuration as explained above):

firstname, lastname, phoneNumber, emailAddress, appointmentRequested, message, address, contactMailCustomStyle, moveInDate, petsInHousehold, numberOfPersons, employmentRelationship, income, salutation, schufaInformationProvided, schufaVerificationCode, sendProfile, profileImageUrl, privacyPolicyAccepted, company, buyReason, ownCapital, hasPreapproval, lotAvailable, numberOfRequiredWorkingPlaces, plannedInvestment, commercialUsage, applicationPackageCompleted

salutation can contain one of: FEMALE, MALE, COMPANY, NO_SALUTATION

Example XML

<expose:contactForm xmlns:expose="http://rest.immobilienscout24.de/schema/search/expose/1.0" xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://rest.immobilienscout24.de/schema/search/expose/1.0 expose-1.0.xsd">

<firstname>firstname</firstname>

<lastname>lastname</lastname>

<phoneNumber>phoneNumber</phoneNumber>

<emailAddress>emailAddress@mail.de</emailAddress>

<appointmentRequested>YES</appointmentRequested>

<message>message</message>

<address xsi:type="common:Address">

<street>street</street>

<houseNumber>houseNumber</houseNumber>

<postcode>12345</postcode>

<city>city</city>

</address>

<salutation>MALE</salutation>

</expose:contactForm>


Example JSON

{

"expose.contactForm":{

"@xmlns":{

"common":"http:\/\/rest.immobilienscout24.de\/schema\/common\/1.0"

},

"firstname":"firstname",

"lastname":"lastname",

"phoneNumber":"phoneNumber",

"emailAddress":"emailAddress@mail.de",

"appointmentRequested":"YES",

"message":"message",

"address":{

"@xsi.type":"common:Address",

"street":"street",

"houseNumber":"houseNumber",

"postcode":"12345",

"city":"city"

},
"salutation":  

}

}

 


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 MESSAGE_OPERATION_SUCCESSFUL


Header

No special headers.


Body


XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<common:messages xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:ns4="http://rest.immobilienscout24.de/schema/platform/gis/1.0">

<message>

<messageCode>MESSAGE_OPERATION_SUCCESSFUL</messageCode>

<message>Operation successful executed.</message>

</message>

</common:messages>


JSON

{

"common.messages":[ {

"message":{

"messageCode":"MESSAGE_OPERATION_SUCCESSFUL",

"message":"Operation successful executed."

}

}]

}

 

Deprecated features:
contactFormType is deprecated, and can be omitted. Possible values for contactFormType were: EMAIL, LONG, PHONE, NONE. The server does not handle the given value in any kind.

Attached to the E-Mail as XML

You are able to attach contact requests additionally as a XML file for an easier software import. The format is OpenImmo Feedback 1.2.5 standard.

The configuration to attach this XML to your E-Mail, you can find in the ScoutManager.

<?xml version="1.0" encoding="UTF-8"?>
-<openimmo_feedback>
<version>1.2.5</version>
 
-<sender>
<name>IS24</name>
<datum>01.12.2015</datum>
<makler_id/>
<regi_id>IS24</regi_id>
</sender>
 
 
-<objekt>
<portal_obj_id>63843270</portal_obj_id>
<oobj_id>63843270</oobj_id>
<expose_url>http:///expose/63843270</expose_url>
<bezeichnung>Test-IS24: Haus Kauf - 2015-08-25 16:04:58 833</bezeichnung>
<strasse>Andreasstraße 10</strasse>
<ort>10243 Berlin</ort>
<land>Deutschland</land>
<stadtbezirk>Friedrichshain (Friedrichshain)</stadtbezirk>
<preis>9.999.999.999,00 €</preis>
<anzahl_zimmer>2</anzahl_zimmer>
<flaeche>5,00</flaeche>
 
-<interessent>
<anrede>Herr</anrede>
<vorname>Testvorname</vorname>
<nachname>Testnachname</nachname>
<firma>Testfirma</firma>
<strasse>Magazinstr. 15-17</strasse>
<plz>10179</plz>
<ort>Berlin</ort>
<tel>+49 30 455644</tel>
<email>team_eule@sandbox.de</email>
 
<anfrage>Die ist der Fliesstext Weitere Daten zum Interessenten; Nutzung der Immobilie: Zur Selbstnutzung; Gewünschter Einzugstermin: 06.11.2015; Haushaltsgröße: Einpersonenhaushalt; Tiere im Haushalt: 2 Katzen; Anstellungsverhältnis: Angestellte(r); Haushaltsnettoeinkommen: 500€ - 1.000€; Eigenkapital: 100.000 - 125.000€; Finanzrahmen geprüft: Ja; SCHUFA-Bonitätscheck: Nein; Bewerbungsunterlagen: vorhanden; Grundstück: nicht vorhanden; Erforderliche Arbeitsplätze: 12; Investitionsvolumen: 100.000 - 250.000 €; Nutzungsart/Branche: weiterer Fliesstext  </anfrage>
 
</interessent>
</objekt>
</openimmo_feedback>