Introduction

The Immowelt listing imports API allows you to import listings into the Immowelt platform.
The API provides endpoints for creating, updating, and deleting listings, as well as managing media files associated to listings.
Use this API to integrate with the Immowelt platform and streamline the listing import process.

Authentication

This section covers the authentication and authorization mechanisms required to access the API.

To authorize requests, include the token in the Authorization header as follows:

Authorization: Bearer <your_token>

Available scopes

This section lists the OAuth 2.0 scopes that you might need to request to access this API, depending on the level of access you need. Many scopes overlap, so it’s best to use a scope that is as restrictive as possible.
The access token issued will only contain the requested scopes.

ℹ️ Scopes are case sensitive

API overview

The Immowelt listing imports API is a RESTful API. The API allows you to interact with resources using verbs: POST, GET, PUT, DELETE.

• To create a new resource : use the POST verb with the resource name

POST /listings

• To query an existing resource : use the GET verb with the resource name and its unique identifier

GET /listings/{externalListingId}

• To query a list of resources : use the GET verb with the resource name

GET /listings

• To update an existing resource : use the PUT verb with the resource name and its unique identifier

PUT /listings/{externalListingId}

• To delete an existing resource : use the DELETE verb with the resource name and its unique identifier

DELETE /listings/{externalListingId}

Naming convention

• All the resources names are defined in plural. For instance: “GET /listings”.
• The supported format is JSON.
• The fields are defined in camelCase.
• The boolean fields start by a “is” prefix.

Specification

The Immowelt listing imports API follows the OpenAPI specification.

API features offered

Business Rules

These specific rules apply to listing data at creation and update :

NOTE: The Sandbox environment listings will be automatically deleted after 90 days since the last write/update. The Sandbox environment listings will not be visible on the website, as of now.

Versioning strategy

The Immowelt listing imports API is constantly being worked on to add features, improvements and bugfixes. This means that you should expect changes to be introduced and documented. Whenever we make a significant change to an endpoint, we will increase the version number used in the path of the resource being requested. The current API version is v1 so all the API request must be performed with this version number in the endpoints.

Example:

POST /v1/listings

The API version number being incremented for major versions releases. The minor versions are released without having to increment this API version number enabling API consumers to benefit from non-breaking and backward-compatible changes and fixes seamlessly.

Backward-compatible changes

We consider the following cases as backward-compatible changes (minor releases):

• Adding new optional parameters
• Adding new endpoints
• Adding new fields to existing API responses
• Changing the order of fields in existing API responses

Supported HTTP status codes

• 2xx for successful operations
• 3xx for redirections
• 4xx for client errors
• 5xx for server errors

Errors

The Immowelt listing imports API follow’s the error response format proposed in RFC 7807 also known as Problem Details for HTTP APIs. As with our normal API responses, your client must be prepared to gracefully handle additional members of the response.
However, some error cases need to be accompanied by a human readable documentation. Especially regarding any errors that might be encountered during the API format validation steps (400 Bad Request) in order to give sufficient information needed by API consumers to fix the parameters and/or the request body. This 400 Bad Request is detailed in the section below.

Validation Error

In addition to the information proposed in RFC 7807, we support “errors” and “errorSource” fields to convey the fine-grained details of the API format validation problems.

Example

{
  "type": "{{API_DOC_URL}}#section/Errors/Validation-Error",
  "title": "Bad request",
  "detail": "Your request has not been validated",
  "instance": "00-652039077ca790cc11d3a80cc29dbeb9-ca5243f0e6c43195-00",
  "errors": [
    {
      "name": "/space",
      "reason": "must NOT have additional properties: space."
    }
  ],
  "errorSource": "body",
  "status": 400
}