OpenImmo API (2.0.0)

Download OpenAPI specification:

REST API of the OpenImmo 2 standard for exchanging real estate data. Software providers use it to create, update and delete listings and projects on a receiving platform and to upload the associated media files.

The standard is maintained by OpenImmo e.V., Verein zur Förderung des Datenaustauschs in der Immobilienwirtschaft.

Listing

CRUD operations about listings.

Create a new listing

This endpoint allows you to create a new classified to be published on the receiving platform's portals. Depending on the parameters sent along with the body payload, the classified can be created but not published. This endpoint returns synchronously a response informing if the body payload format is valid or not. In the case of a valid format, the endpoint will return a 202 Accepted HTTP status code with URL links to related resources. In the case of invalid format, the endpoint will return a 400 Invalid format HTTP status code with the details of the rejection's reasons

Authorizations:
BearerToken
Request Body schema: application/json; charset=utf-8
required
object (data)
required
object (metadata)

Metadata associated with the listing in the receiving platform

Array of objects (userDefined)

en=Area for extended Data, not expilitly defined. As ARRAY. Every item has name, value with a type and modus. modus can be free used i.e. for defining CRUD atrributes. ;de= Der Bereich für -User Defined Daten- z.B. zum bilateralen Austausch zwischen Partnern

Array of objects (mediaRequest)

Array of media items to attach to the listing.

object (contact)

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "data": {
    },
  • "metadata": {
    },
  • "userDefined": [
    ],
  • "media": [
    ],
  • "contact": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "requestId": "0196106c-409b-7fg4-a317-db7393a36b77",
  • "listingId": "a1b2c3d4-e5f6-4789-b0a1-c2d3e4f5a6b7",
  • "externalListingId": "offererEstateId123",
  • "warnings": [
    ]
}

Retrieves all listings for a customer.

Retrieve all listings for a customer. To fetch nextPage, use the GET /listings?nextPageToken={token} in this endpoint. To retrieve a specific listing, use the GET /listings/{externalListingId} endpoint.

Authorizations:
BearerToken
query Parameters
nextPageToken
string

The token to retrieve the next page of results. This token is returned in the response of this endpoint when the number of listings exceeds the page size. To retrieve the first page of results, do not include this parameter in the request.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "externalListingIds": [
    ],
  • "nextPageToken": "string"
}

Retrieve an existing listing

Retrieves a listing

Authorizations:
BearerToken
path Parameters
externalListingId
required
string
Example: 2592IWF02EC6

The Unique Identifier of the listing. Can be:

  • Your own offererEstateId that was used when creating a listing

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "listing": {
    }
}

Update an existing listing

Updates a listing

Authorizations:
BearerToken
path Parameters
externalListingId
required
string
Example: 2592IWF02EC6

The Unique Identifier of the listing. Can be:

  • Your own offererEstateId that was used when creating a listing
Request Body schema: application/json; charset=utf-8
required
object (data)
required
object (metadata)

Metadata associated with the listing in the receiving platform

Array of objects (userDefined)

en=Area for extended Data, not expilitly defined. As ARRAY. Every item has name, value with a type and modus. modus can be free used i.e. for defining CRUD atrributes. ;de= Der Bereich für -User Defined Daten- z.B. zum bilateralen Austausch zwischen Partnern

Array of objects (mediaRequest)

Array of media items to attach to the listing.

object (contact)

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "data": {
    },
  • "metadata": {
    },
  • "userDefined": [
    ],
  • "media": [
    ],
  • "contact": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "requestId": "0196106c-409b-7fg4-a317-db7393a36b77",
  • "listingId": "a1b2c3d4-e5f6-4789-b0a1-c2d3e4f5a6b7",
  • "externalListingId": "offererEstateId123",
  • "warnings": [
    ]
}

Delete an existing listing

Deletes a listing

Authorizations:
BearerToken
path Parameters
externalListingId
required
string
Example: 2592IW-F02EC6

The Unique Identifier of the listing. Can be:

  • Your own offererEstateId that was used when creating a listing

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "requestId": "0196106c-409b-7fg4-a317-db7393a36b77",
  • "listingId": "a1b2c3d4-e5f6-4789-b0a1-c2d3e4f5a6b7",
  • "externalListingId": "offererEstateId123"
}

Media

Request presigned URLs to upload media files.

Request a presigned URL for media upload

Request a presigned URL to upload a media file to the system. The presigned URL is valid for 60 seconds. During this time:

  • The upload must be completed.
  • The media must be attached to a listing.

If these conditions are not met, the media will be automatically deleted. Supported media types include images, videos, and other multimedia content. Note: The maximum file size allowed is 40MB.

Authorizations:
BearerToken
Request Body schema: application/json; charset=utf-8
externalMediaId
required
string non-empty

The ID of the media into the software

fileName
required
string non-empty .*\S.*

The name of the media file.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "externalMediaId": "media_01",
  • "fileName": "my_media.jpg"
}

Response samples

Content type
application/json; charset=utf-8
{}

Health

Health of the service.

Healthcheck endpoint

Get the operational status of the API

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json; charset=utf-8
Example
{
  • "type": "/components/schemas/internalServerErrorResponse",
  • "status": 500,
  • "title": "Internal server error",
  • "detail": "Something went wrong, please try again later or if the problem persists please contact the support with the instance id",
  • "instance": "00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01"
}

Listing

required
object (data)
required
object (metadata)

Metadata associated with the listing in the receiving platform

Array of objects (userDefined)

en=Area for extended Data, not expilitly defined. As ARRAY. Every item has name, value with a type and modus. modus can be free used i.e. for defining CRUD atrributes. ;de= Der Bereich für -User Defined Daten- z.B. zum bilateralen Austausch zwischen Partnern

Array of objects (mediaRequest)

Array of media items to attach to the listing.

object (contact)
{
  • "data": {
    },
  • "metadata": {
    },
  • "userDefined": [
    ],
  • "media": [
    ],
  • "contact": {
    }
}

Media upload request

externalMediaId
required
string non-empty

The ID of the media into the software

fileName
required
string non-empty .*\S.*

The name of the media file.

{
  • "externalMediaId": "media_01",
  • "fileName": "my_media.jpg"
}

Error Response

type
required
string

The URI reference that identifies the problem type. The "about:blank" URI, when used as a problem type, indicates that the problem has no additional semantics beyond that of the HTTP status code.

status
required
number

The HTTP status code generated for this occurrence of the problem

title
required
string

A human-readable summary of the problem type

detail
required
string

A human-readable explanation specific to this occurrence of the problem

instance
required
string

A URI reference that identifies the specific occurrence of the problem

errorSource
string

The source of the error

{
  • "type": "/components/schemas/validationContentTypeErrorResponse",
  • "status": 400,
  • "title": "Bad Request",
  • "detail": "Request content type is not application/json; charset=utf-8",
  • "instance": "00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01",
  • "errorSource": "headers"
}