Domoplius import V2

Quick start

Create a UTF-8 XML or JSON document and publish it at a public HTTP(S) URL. Each successful response is the complete current snapshot supplied by that URL.

1. 1Choose the XML or JSON starter, replace its sample values, and check your category in the field reference.
2. 2Give each listing a stable external_id and do not repeat it within the same category.
3. 3Publish the feed at a public URL and send the URL and listing-owner account to your Domoplius contact.

XML and JSON are structural templates. Verify numeric location/option IDs and photo URLs.

<?xml version="1.0" encoding="UTF-8"?>
<domoplius xmlns="https://domoplius.lt/xml/import/v2" version="2">
  <!--Replace location and option IDs using the versioned endpoints, and supply public image URLs.-->
  <listings>
    <flat>
      <external_id>100001</external_id>
      <action_type>1</action_type>
      <price_eur>145000</price_eur>
      <administrative_unit_id>461</administrative_unit_id>
      <settlement_id>1</settlement_id>
      <flat_size>50.5</flat_size>
      <flat_rooms>1</flat_rooms>
    </flat>
  </listings>
</domoplius>

Import lifecycle

Every source run follows the same stages. A record-level failure does not stop valid records, but feed reliability determines whether missing listings can be removed.

1. 1. Download

   The importer securely downloads the public HTTP(S) feed while enforcing size, time, and redirect limits.

2. 2. Preflight

   It verifies the V2 namespace, version, flat listing fields, collection structure, unique identities, and that no DTD or external entities are present.

3. 3. Streaming parse

   Records are read one at a time, normalised, validated, and resolved against category and location values.

4. 4. Persistence

   Valid records are created or updated; invalid records are skipped and included in the report.

5. 5. Reconciliation

   Missing listings are considered only after every enabled source for the owner succeeds and deletion safeguards pass.

6. 6. Report

   An administrator reviews the outcome, warnings, and rejected-record reasons before enabling or leaving the source active.

Feed requirements

Follow these core rules so an XML or JSON feed can be imported.

Prices and short rent

Send EUR prices with up to two decimal places and a decimal point, for example 10.01. Actions 1 and 3 require price_eur. Action 9 is supported only for domestic flats and buildings and requires short_rent_day_eur; price_eur is optional and cleared when omitted.

Land area

Use site_size_a in ares (1 are = 100 m²). Omit optional land area to clear it.

Empty values and native types

Whitespace-only XML scalars and JSON null clear optional values. Empty JSON strings clear string fields; they are invalid numeric or boolean values. Missing required or conditionally required values reject that listing. Missing or empty contact_name, contact_phone and contact_email fall back to the matched broker, then the source owner; they are not cleared. Owner assignment requires the source fallback setting when no broker matches. contact_secondary_phone has no fallback and is cleared when omitted.

Semantic checks

Validate the feed before handover. The validator checks required fields, accepted values, address relationships and paired coordinates. Invalid field values reject that listing; structural errors reject the entire feed. See the field reference for exact constraints.

Commercial purposes

For commercial and foreign_commercial, use commercial_room_purposes with IDs from the field reference. XML contains repeated commercial_room_purpose_id elements; JSON uses an array such as "commercial_room_purposes": [408, 410]. Use a collection even for one purpose. Omission or an empty list clears previous purposes.

XML structure and encoding

Use UTF-8 XML with <domoplius xmlns="https://domoplius.lt/xml/import/v2" version="2"><listings>…</listings></domoplius>. Scalar listing fields are direct category children; the repeated features, photos, and commercial_room_purposes collections are nested.

JSON structure and encoding

Use UTF-8 JSON with a top-level listings array and no version property. Each item contains category and its fields directly; features, photos, and commercial_room_purposes are arrays.

CDATA and safety

CDATA is allowed for text. DTD, DOCTYPE, and external entities are prohibited and cause the feed to be rejected.

Text

HTML tags are stripped from descriptions and <br> becomes a newline. Send content, not a preformatted page layout.

Numbers and dates

Use a dot as the decimal separator for prices and other numbers. Construction and reconstruction dates accept YYYY or YYYY-MM.

Public URL

HTTP and HTTPS are supported; HTTPS is recommended and must use a valid certificate. A direct GET must return the XML or JSON feed without login, cookies, or a JavaScript challenge. Safe redirects are supported, but a direct URL is preferred.

How listings are updated

Domoplius identifies a listing by the Domoplius account (listing owner), category, and external_id. Do not change this identity when other listing data changes.

New listing

A new external_id creates a new listing. The ID must be positive, permanent, and unique within its category for the same Domoplius account.

Update

The same category and external_id update the existing listing for that account, even when the record moves between its registered XML URLs. The same external_id may identify a different listing in another category.

Category change

Moving a record to another category creates a new identity. The previous category record becomes missing and may be removed.

Complete snapshot

After a successful download, records omitted from that URL—including every record in an omitted category—are no longer supplied by that source. Membership in any non-retired source protects the listing, including disabled or archived sources. Retire a source explicitly to release that protection.

Validation and errors

Failures are handled at two levels: a single listing may be isolated, while a feed-reliability failure stops the complete run and missing-listing reconciliation.

Lithuanian and foreign locations

Foreign listings use country_id and city_id from the country/city endpoints; the city must belong to its country. Lithuanian listings use existing active numeric Domoplius administrative_unit_id, settlement_id, microdistrict_id, and street_id values. They map directly to placereg_* records and must form one hierarchy.

1. 1. Administrative unit

   Use the returned numeric id.

   /api/v2/imports/locations/administrative-unitsCopy

   GET /api/v2/imports/locations/administrative-units

2. 2. Settlement

   Filter by administrative_unit_id.

   /api/v2/imports/locations/settlements?administrative_unit_id=461Copy

   GET /api/v2/imports/locations/settlements?administrative_unit_id=461

3. 3. Microdistrict

   When applicable, filter by settlement_id.

   /api/v2/imports/locations/microdistricts?settlement_id=1Copy

   GET /api/v2/imports/locations/microdistricts?settlement_id=1

4. 4. Street

   Filter by settlement_id and, when needed, microdistrict_id.

   /api/v2/imports/locations/streets?settlement_id=1Copy

   GET /api/v2/imports/locations/streets?settlement_id=1

<administrative_unit_id>461</administrative_unit_id>
<settlement_id>1</settlement_id>
<microdistrict_id>31</microdistrict_id>
<street_id>22328</street_id>

Photos and video

Include photo and video references in each listing record.

Order and cover photo

Send up to 30 URLs in the desired order. The first successfully prepared photo becomes the cover and the remaining order is preserved.

Photo URLs

Use public HTTP(S) addresses that Domoplius can download without signing in.

Clearing photos

Send the complete desired set on every run. If photos is absent or empty, previously imported photos are removed.

YouTube video

Use video_url with an absolute http:// or https:// YouTube URL: watch?v=, youtu.be/, embed/, shorts/, v/ or vi/. youtube-nocookie.com embeds are supported. Bare video IDs are not accepted in V2. Omit it to clear the previous video.

XML, XSD, JSON, and JSON Schema

XML/XSD and JSON/JSON Schema are generated from the same V2 field registry.

XML and JSON are structural templates. Verify numeric location/option IDs and photo URLs.

<?xml version="1.0" encoding="UTF-8"?>
<domoplius xmlns="https://domoplius.lt/xml/import/v2" version="2">
  <!--Replace location and option IDs using the versioned endpoints, and supply public image URLs.-->
  <listings>
    <flat>
      <external_id>100001</external_id>
      <action_type>1</action_type>
      <contact_name>Partnerio brokeris</contact_name>
      <contact_phone>+37060000000</contact_phone>
      <contact_email>[email protected]</contact_email>
      <price_eur>145000</price_eur>
      <administrative_unit_id>461</administrative_unit_id>
      <settlement_id>1</settlement_id>
      <microdistrict_id>31</microdistrict_id>
      <street_id>22328</street_id>
      <building_number>12A</building_number>
      <unit_number>4</unit_number>
      <hide_unit_number>false</hide_unit_number>
      <latitude>54.687157</latitude>
      <longitude>25.279652</longitude>
      <description>Šviesus butas.</description>
      <flat_size>50.5</flat_size>
      <flat_rooms>1</flat_rooms>
      <window_directions>n,e</window_directions>
      <features>
        <feature_id>79</feature_id>
      </features>
      <photos>
        <photo_url>https://example.lt/photo.jpg</photo_url>
      </photos>
    </flat>
    <commercial>
      <external_id>100002</external_id>
      <action_type>1</action_type>
      <contact_name>Partnerio brokeris</contact_name>
      <contact_phone>+37060000000</contact_phone>
      <contact_email>[email protected]</contact_email>
      <price_eur>145000</price_eur>
      <administrative_unit_id>461</administrative_unit_id>
      <settlement_id>1</settlement_id>
      <microdistrict_id>31</microdistrict_id>
      <street_id>22328</street_id>
      <building_number>12A</building_number>
      <unit_number>4</unit_number>
      <latitude>54.687157</latitude>
      <longitude>25.279652</longitude>
      <description>Komercinės patalpos.</description>
      <is_price_for_all_place>false</is_price_for_all_place>
      <commercial_room_size>50.5</commercial_room_size>
      <commercial_room_purposes>
        <commercial_room_purpose_id>408</commercial_room_purpose_id>
        <commercial_room_purpose_id>410</commercial_room_purpose_id>
      </commercial_room_purposes>
      <features/>
      <photos>
        <photo_url>https://example.lt/photo.jpg</photo_url>
      </photos>
    </commercial>
  </listings>
</domoplius>

{
    "listings": [
        {
            "category": "flat",
            "external_id": 100001,
            "action_type": 1,
            "contact_name": "Partnerio brokeris",
            "contact_phone": "+37060000000",
            "contact_email": "[email protected]",
            "price_eur": 145000,
            "administrative_unit_id": 461,
            "settlement_id": 1,
            "microdistrict_id": 31,
            "street_id": 22328,
            "building_number": "12A",
            "unit_number": "4",
            "hide_unit_number": false,
            "latitude": 54.687157,
            "longitude": 25.279652,
            "description": "Šviesus butas.",
            "flat_size": 50.5,
            "flat_rooms": 1,
            "window_directions": "n,e",
            "features": [
                79
            ],
            "photos": [
                "https://example.lt/photo.jpg"
            ]
        },
        {
            "category": "commercial",
            "external_id": 100002,
            "action_type": 1,
            "contact_name": "Partnerio brokeris",
            "contact_phone": "+37060000000",
            "contact_email": "[email protected]",
            "price_eur": 145000,
            "administrative_unit_id": 461,
            "settlement_id": 1,
            "microdistrict_id": 31,
            "street_id": 22328,
            "building_number": "12A",
            "unit_number": "4",
            "latitude": 54.687157,
            "longitude": 25.279652,
            "description": "Komercinės patalpos.",
            "is_price_for_all_place": false,
            "commercial_room_size": 50.5,
            "commercial_room_purposes": [
                408,
                410
            ],
            "features": [],
            "photos": [
                "https://example.lt/photo.jpg"
            ]
        }
    ]
}

Common mistakes

Changing identity

Changing external_id or category creates a different identity and may mark the previous listing as missing.

Using undocumented names or structure

Unknown fields, plural category elements, and the old contact, pricing, location, content, or attributes groups are rejected.

Using the wrong location identity

Lithuanian locations require existing numeric Domoplius IDs; foreign locations require the published numeric country and city IDs.

Omitting photos

The common V2 snapshot rule applies to photos: omission clears previously imported photos.

Sending video_url as a boolean

Send a supported URL. A boolean does not identify a video.

Clearing a required field

Required and conditionally required data must remain valid in every record; an empty element rejects that record.

Versions and changes

V2 is the default for new sources. XML and JSON share the same field contract and complete-snapshot semantics.

Change history

Import V2 · 2026-09-17

Current V2 contract: XML and JSON complete snapshots, ten categories, numeric location IDs, EUR prices, land area in ares, commercial-purpose collections and absolute HTTP(S) YouTube URLs. Generated examples, XSD and JSON Schema describe this contract.