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 [email protected].

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 [email protected].

Immowelt

To forward only the notifications from Immowelt you can filter incoming emails based on the sender [email protected] and the title containing Kontaktanfrage. Alternatively you can filter on the CC address [email protected].

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

{
  "eventType": "[event-type]",
  "eventPayload": {}
}

The requestReceived event

To get notified about new requests EstateSync receives, you can create a webhook that reacts to the requestReceived 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 publicationSucceeded event

To get notified about successful updates of listings, you can create a webhook that reacts to the publicationSucceeded 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": "update" // or "create" or "delete"
}

The publicationFailed event

To get notified about failed updates of listings, you can create a webhook that reacts to the publicationFailed 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": "update" // or "create" or "delete"
}

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
{