EstateSync (0.1)

Download OpenAPI specification:Download

Introduction

Use the EstateSync API to easily distribute real estate data to major German market places. Send your data once – publish it on all the platforms.

If you are building a real estate application you often need to bring offers to platforms like Immobilienscout24, Immowelt or Ebay Kleinanzeigen. Some of them have their own API, some of them use OpenImmo. Some use old FTP servers to transfer data, some complicated OAuth flows. EstateSync exposes one beautiful API so you don't have to worry about all of that.

Basic Terminology

Account

An account represents your access to the API. It holds all entities you can access and modify.

Property

A property is the physical real estate - with a type, fields and attachments.

Target

A target represents a platform like Ebay Kleinanzeigen or Immobilienscout24. It is called a target because your properties should be distributed there eventually.

Listing

A listing represents a property on a target. Create a listing to "publish" a property to a target. When you update a property all of its listings will automatically be updated as well. This way the platforms always have the newest version of the property. Delete a listing to "unpublish" a property from a target.

Contact

A contact represents a person who is responsible for one or more properties. Usually platforms display the details of the contact (name, phone number, email, …) besides the listing.

Request

A request represents the contact inquiry a potential customer can submit on the target platforms. The request usually contains a message and details about the prospect.

Configuring Contact Requests

For every submitted prospect inquiry the targets send a notification to the email of the contact of the listed property. You need to forward these notifications to {emailId}@requests.estatesync.io where emailId is the identifier that is provided for every target (either in the response of a create or get target request). An example address to forward your request emails to might look like immowelt-ABCdef78956789abc123@requests.estatesync.io.

Immobilienscout24

To forward only the notifications from Immobilienscout24 (and not other marketing or support emails) you can simply filter incoming emails based on the sender anfrage@immobilienscout24.de.

Immowelt

To forward only the notifications from Immowelt you can filter incoming emails based on the sender info@immowelt.de and the title containing Kontaktanfrage. Alternatively you can filter on the CC address objektanfragen@immowelt.de.

Working with Webhooks

By using webhooks EstateSync can notify you about events that you would need to query the API for otherwise. Every webhook can be triggered by the events that you pass when creating the webhook (see section "Webhooks"). EstateSync attempts to POST with an application/json body to the URL you supply. The content has the form

{
  "eventName": "[event_name]",
  "eventPayload": {},
  "eventTime": "[event_time_ISO_string]"
}

The request.created event

To get notified about new requests EstateSync receives, you can create a webhook that reacts to the request.created event. The eventPayload field of the body will contain the request. It has the same structure as requests returned by GET /requests/{id}. For more information on how to get these notifications see the section "Configuring Contact Requests".

The request.parsing_failed event

To get notified about requests that EstateSync receives but cannot parse, you can create a webhook that reacts to the request.parsing_failed event. The eventPayload field of the body will contain details of the received email and why it could not be parsed as a request.

This event can occur when you forward emails to EstateSync that are not real contact requests from a target platform and hence do not include an XML attachment. The best way to prevent this is to setup email forwarding based on the sender address as described in the "Configuring Contact Requests" section.

{
  "targetId": "[id-of-the-email-target]",
  "createdAt": "[ISO-datetime-of-failure]",
  "failureCode": "[short-error-code]",
  "failureMessage": "[readable-error-description]",
  "sender": "[sender-address-of-the-email]",
  "recipient": "[recipient-address-of-the-email]",
  "subject": "[subject-of-the-email]",
  "body": "[body-of-the-email]",
}

The publication.succeeded event

To get notified about successful updates of listings, you can create a webhook that reacts to the publication.succeeded event. The eventPayload field contains an object with details of the publication:

{
  "listingId": "[id-of-the-concerned-listing]",
  "propertyId": "[id-of-property-of-the-listing]",
  "targetId": "[id-of-the-target-of-the-listing]",
  "type": "set" // or "delete"
}

The publication.failed event

To get notified about failed updates of listings, you can create a webhook that reacts to the publication.failed event. The eventPayload field contains an object with the publication as well as details of the failure:

{
  "failureCode": "[short-error-code]",
  "failureMessage": "[readable-error-description]",
  "listingId": "[id-of-the-concerned-listing]",
  "propertyId": "[id-of-property-of-the-listing]",
  "targetId": "[id-of-the-target-of-the-listing]",
  "type": "set" // or "delete"
}

The property.processing_succeeded event

To get notified about successfully finished processings of properties (e.g. when all attachments are fetched), you can create a webhook that reacts to the property.processing_succeeded event. The eventPayload field of the body will contain the processed property.

The property.processing_failed event

To get notified about unsuccessful processings of properties (e.g. when an attachment could not be fetched due to a not-found response), you can create a webhook that reacts to the property.processing_failed event. The eventPayload field of the body will contain the processed property as well as details of the failure.

{
  "failureCode": "[short-error-code]",
  "failureMessage": "[readable-error-description]",
  // ... all other attributes of the property
}

Authentication

api-key

When you sign up for an account a first API key will be automatically added. You can use it to publish and modify resources. Estate Sync uses Bearer Authentication. Just provide the header Authorization with the value Bearer {your-api-key}.

Security Scheme Type HTTP
HTTP Authorization Scheme Bearer

Account

Get your account

Return information of your API account.

Authorizations:

Responses

200

OK

get /account
https://api.estatesync.io/account

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Immobilienscout24 Consumer Credentials

Update your consumer credentials for Immobilienscout24. Necessary to be able to create targets of type immobilienscout-24.

Authorizations:
Request Body schema: application/json
key
required
string
secret
required
string

Responses

200

OK

400

Bad Request

put /account/credentials/immobilienscout-24
https://api.estatesync.io/account/credentials/immobilienscout-24

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Immobilienscout24 Sandbox Consumer Credentials

Update your consumer credentials for the Immobilienscout24 Sandbox. Necessary to be able to create targets of type immobilienscout-24-sandbox.

Authorizations:
Request Body schema: application/json
key
required
string
secret
required
string

Responses

200

OK

400

Bad Request

put /account/credentials/immobilienscout-24-sandbox
https://api.estatesync.io/account/credentials/immobilienscout-24-sandbox

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}

Properties

Create a property

Add a new property to your account.

Authorizations:
Request Body schema: application/json
One of
  • Apartment Rent
  • Apartment Buy
  • House Rent
  • House Buy
  • Plot Rent
  • Plot Buy
type
required
any
Value: "apartmentRent"

The type of the property. Cannot be changed afterwards.

fields
required
object
attachments
Array of objects <= 150 items
contactId
string 20 characters

References a contact. Can be left out to use the default contact of the target platform.

Responses

201

Created

400

Bad Request

post /properties
https://api.estatesync.io/properties

Request samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
}

List all properties

Return all properties of your account.

Authorizations:

Responses

200

OK

get /properties
https://api.estatesync.io/properties

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
]

Get a property

Return a specific property of your account.

Authorizations:
path Parameters
id
required
string

The ID of the property.

Responses

200
404

Not Found

get /properties/{id}
https://api.estatesync.io/properties/{id}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{