Skip to content

Retrieve Ticket URL to Embed On Top Offer Widget

BETA
Get Permission

This endpoint returns a ticket containing a URL and its expiration time which you can use to embed a widget into your application via an iFrame. Customers can then use the functionality within the rendered widget to purchase ImmoScout24 products.

POST /restapi/api/offer/v1.0/user/me/realestate/{id}|ext-{external-id}/ontop/ticket

Supported media types:
JSON

Note

  • A ticket consists of a URL and an expiration date. It represents a specific session for showing the widget.
  • A ticket can be re-used for the same real estate and user as long as it is still valid. Make sure that the ticket has at least 10 minutes validity left before passing it to the front end. Otherwise the widget might render an error.
  • The expiration time is currently set to 24h and is subject to change. We ask that you respect the expiration time and make sure to request a new ticket in time.
  • The real estate must be already published before a purchase can take place.
  • Commercial real estate types are currently not supported (office, store, industry, trade site, special purpose)
  • To use this endpoint we expect that you provide the request via the 3-legged OAuth 1 flow.

Request

Path Parameters

Parameter Value Description
realEstateId e.g. 1234654 The ImmoScout24 real estate ID or external ID for which the widget should display prices and booking functionality. Please be aware that the prices vary depending on the real estate type, region, and customer type.

Body Parameters

Parameter Value Description
returnUrl https://www.example.com/your-return-url Our Checkout will use your website's URL to redirect the users back to it once they have completed or canceled the purchase. Please make sure to supply an HTTPS. This is a mandatory field.
Example Request

https://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/me/realestate/1234654/ontop/ticket

JSON Body
1
2
3
{
  "returnUrl": "https://www.example.com/your-return-url"
}

Response

Field Value Description
expiration 2020-05-06T14:34:59.123Z The time when the given URL will expire. The timestamp is formatted as ISO 8601.
url https://www.immobilienscout24.de/on-top-offer/widget/ticket/abcdef123456/widget.html The url to include in an iframe so that the widget can be rendered directly from ImmoScout24's domain.
JSON
1
2
3
4
{
  "expiration": "2020-05-06T14:34:59.123Z",
  "url": "https://www.immobilienscout24.de/on-top-offer/widget/ticket/abcdef123456/widget.html"
}

Possible Errors

404 - Realestate not found.

403 - OAuth token is invalid or real estate id doesn't belong to user.

422 - Real estate type is not supported (currently, commercial real estate types are not supported)

Please keep in mind that if the timestamp within the ticket has expired the widget will show an error.