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

FieldDescriptionRequiredValidation
titleTitle of the advert.Requiredstring
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.
descriptionDescription of the advert.Requiredstring
65535 chars max
50 chars min
category_urnURN of the advert category.RequiredUnique category identifier (see Taxonomy API)
contact.nameName of the contact person for advert customizationRequired*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.emailE-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.phonePhone number of contact person for advert customization.Optionalstring
7 digits min
14 digits max
contact.photoPhoto of the contact person for advert customization.Optionalstring with a valid url of an image
max: 1MB
min width: 100px
min height: 100px
pricePrice value of the advert.Requiredint or float
0 (zero) to hide price and display it as "on demand" (only for Investments and Units). See more about hidden price.
price.currencyPrice currency.RequiredAccepted values are:
Otodom: PLN, EUR, GBP
Imovirtual: EUR
Storia: EUR, RON
rent_price.valueSets the optional rent price for "for sale" categories.OptionalOtodom/Storia only
int or float
rent_price.currencySets the currency for the optional rent price.OptionalOtodom/Storia only
Accepted values are PLN, EUR, GBP.
deposit_price.valueSets the optional deposit value for "for rent" categories.OptionalOtodom/Storia only
int or float
deposit_price.currencySets the currency for the optional deposit value.OptionalOtodom/Storia only
Accepted values are PLN, EUR, GBP.
marketDefines the type of market for the advert.OptionalAccepted values are secondary (default if omitted) or primary.
parent_uuidUUID of the parent advert. Only valid for primary market adverts.OptionalRefer to Primary Market for more information.
location.lat
location.lon
Latitude and Longitude of advert location.Requireddecimal degrees (e.g. 38.66287, -9.075342)
must be the country site coordinate
location.exactDetermines if the exact location of the advert will be shown on a map.Optionalboolean
Accepted values are false (default if omitted) or true. Only available if coordinates are in the request.
images.urlURL of an advert image.RequiredArray, at least one must be sent.
Smallest side must have at least 300px.
HTTP response status code need to be 200.
movie_urlThe URL for a Youtube or Vimeo movie to be displayed on the advert detail page.OptionalMust be a valid Youtube or Vimeo URL (shortlinks are not accepted)
virtual_walkThe URL for a Youtube, Vimeo or a Matterport movie to be displayed on the advert detail page.OptionalMust be a valid URL from Youtube, Vimeo, Cupix](https://www.cupix.com/), Matterport or Kuula
(shortlinks are not accepted)
floor_planURL of an image.OptionalMust be a valid image URL.
(shortlinks are not accepted)
attributes.urnURN of an attribute.OptionalRefer to the Taxonomy API for more information.
attributes.valueThe value of the attribute.OptionalRefer 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_urnint
Refer to the Taxonomy API for more information.
Also, check here
which are the areas available for each category.
attributes.urn > urn:concept:register-numberRegistration number for local accommodationRequired for category_urn urn:concept:realestate-for-vacationImovirtual only
int
must contain only the value of register number itself, we will add "/AL" automatically.
site_urnThe site where the advert will be published to.RequiredRefer to Supported Sites for more information.
custom_fields.idInternal advert ID generated from your own application.Requiredstring
custom_fields.reference_idAn optional reference for the advert.Optionalstring
dates related attributes
e.g
urn:concept:free-from
urn:concept:start-date
Attributes related to datesOptionalstring format [YYYY-MM-DD]
auto_extendDetermines whether advert has to be automatically extended or notOptionalboolean
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.