Advert payload and validation rules
Below you can check the structure of an advert payload, a description of each field, and each field validation rules.
Advert additional information
This table describes only the main structure of the advert. In addition to this, an advert can also contain a number of attributes and/or characteristics.
Which can be consulted in the Taxonomy API.
For a complete example of what an advert looks like, check out our API Reference.
Also, you can check out the example under Publishing Adverts.
Advert Payload and Validation Rules
Field | Description | Required | Validation |
---|---|---|---|
title | Title of the advert. | Required | string 70 chars max (Storia.ro) 50 chars max (Imovirtual.pt, Otodom.pl) 5 chars min (publication fails if limits are exceeded, title is not truncated). Title should not contain uppercase string. |
description | Description of the advert. | Required | string 65535 chars max 50 chars min |
category_urn | URN of the advert category. | Required | Unique category identifier (see Taxonomy API) |
contact.name | Name of the contact person for advert customization | Required* | string Name should not contain uppercase string. *Required if contact field is present in the payload. In case of no contact field in the payload, the default contact details will be applied. |
contact.email | E-mail number of the contact person for advert customization. | Required* | string with a valid e-mail address *Required if contact field is present in the payload. In case of no contact field in the payload, the default contact details will be applied. |
contact.phone | Phone number of contact person for advert customization. | Optional | string 7 digits min 14 digits max |
contact.photo | Photo of the contact person for advert customization. | Optional | string with a valid url of an image max: 1MB min width: 100px min height: 100px |
price | Price value of the advert. | Required | int or float 0 (zero) to hide price and display it as "on demand" (only for Investments and Units). See more about hidden price. |
price.currency | Price currency. | Required | Accepted values are: Otodom: PLN , EUR , GBP Imovirtual: EUR Storia: EUR , RON |
rent_price.value | Sets the optional rent price for "for sale" categories. | Optional | Otodom/Storia only int or float |
rent_price.currency | Sets the currency for the optional rent price. | Optional | Otodom/Storia only Accepted values are PLN , EUR , GBP . |
deposit_price.value | Sets the optional deposit value for "for rent" categories. | Optional | Otodom/Storia only int or float |
deposit_price.currency | Sets the currency for the optional deposit value. | Optional | Otodom/Storia only Accepted values are PLN , EUR , GBP . |
market | Defines the type of market for the advert. | Optional | Accepted values are secondary (default if omitted) or primary . |
parent_uuid | UUID of the parent advert. Only valid for primary market adverts. | Optional | Refer to Primary Market for more information. |
location.lat location.lon | Latitude and Longitude of advert location. | Required | decimal degrees (e.g. 38.66287, -9.075342) must be the country site coordinate |
location.exact | Determines if the exact location of the advert will be shown on a map. | Optional | boolean Accepted values are false (default if omitted) or true . Only available if coordinates are in the request. |
images.url | URL of an advert image. | Required | Array, at least one must be sent. Smallest side must have at least 300px. HTTP response status code need to be 200. |
movie_url | The URL for a Youtube or Vimeo movie to be displayed on the advert detail page. | Optional | Must be a valid Youtube or Vimeo URL (shortlinks are not accepted) |
virtual_walk | The URL for a Youtube, Vimeo or a Matterport movie to be displayed on the advert detail page. | Optional | Must be a valid URL from Youtube, Vimeo, Cupix](https://www.cupix.com/), Matterport or Kuula (shortlinks are not accepted) |
floor_plan | URL of an image. | Optional | Must be a valid image URL. (shortlinks are not accepted) |
attributes.urn | URN of an attribute. | Optional | Refer to the Taxonomy API for more information. |
attributes.value | The value of the attribute. | Optional | Refer to the Taxonomy API for more information. |
attributes.urn > urn:concept:net-area-m2 and urn:concept:gross-area-m2 and urn:concept:terrain-area-m2 and urn:concept:usable-area-m2 | URN for an area attribute. | Required for some category_urn | int Refer to the Taxonomy API for more information. Also, check here which are the areas available for each category. |
attributes.urn > urn:concept:register-number | Registration number for local accommodation | Required for category_urn urn:concept:realestate-for-vacation | Imovirtual only int must contain only the value of register number itself, we will add "/AL" automatically. |
site_urn | The site where the advert will be published to. | Required | Refer to Supported Sites for more information. |
custom_fields.id | Internal advert ID generated from your own application. | Required | string |
custom_fields.reference_id | An optional reference for the advert. | Optional | string |
dates related attributes e.g urn:concept:free-from urn:concept:start-date | Attributes related to dates | Optional | string format [YYYY-MM-DD] |
auto_extend | Determines whether advert has to be automatically extended or not | Optional | boolean Accepted values are false or true (default if omitted) |
Some extra validations are required to successfully publish adverts in the OLX platform. Check here which are.
Updated 13 days ago