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 Postman Collection.
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 (Imovirtual.pt, Storia.ro) 50 chars max (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
contact.phone	Phone number of contact person for advert customization.	Required	string 7 digits min 14 digits max
contact.email	E-mail number of the contact person for advert customization.	Required	string with a valid e-mail address
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", except for investments category.
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.postal_code	Postal code of advert location.	Optional (Only required if coordinates are not in the request.)	*Imovirtual only* Note: when lat/lon are provided, postal code is ignored. Check available Portuguese CP on CTT site.
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]

Some extra validations are required to successfully publish adverts in the OLX platform. Check here which are.