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" (the logic differs depending on the marketplace). See more about the 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

string
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.