How to connect a website to voxCRM

The voxCRM system provides a public XML API (with a JSON option), thanks to which a website can retrieve up-to-date data about investments, available units and price change history in a fully automated way. The data in the XML file is automatically updated once per hour — we recommend caching on the website side.

Table of contents

1. Endpoint — Investment list
2. Endpoint — List of units for an investment
3. Endpoint — Price change history
4. Dictionaries: statuses, unit types and cardinal directions
5. Integration examples
6. Contact

1. Endpoint — Investment list

URL (XML — default format):

GET https://demo1.voxdeveloper.com/webservice/investments-list/api_key/{API_KEY}

Example for the demo instance (XML):
https://demo1.voxdeveloper.com/webservice/investments-list/api_key/ab33c2fb8240c8c7ca015d924713b5d234b7778e

JSON version — the same endpoint returns data in JSON format after adding the /json/1 segment to the address:

GET https://demo1.voxdeveloper.com/webservice/investments-list/api_key/{API_KEY}/json/1

Example for the demo instance (JSON):
https://demo1.voxdeveloper.com/webservice/investments-list/api_key/ab33c2fb8240c8c7ca015d924713b5d234b7778e/json/1

Default fields (always returned)

Optional fields (depending on settings)

These fields will appear in the XML only when the administrator has enabled the corresponding option. If you want to use any of them, ask the administrator to enable it.

XML example

<?xml version="1.0"?>
<xml>
  <investment>
    <id>123</id>
    <name>Test Investment</name>
    <voivodeship>mazowieckie</voivodeship>
    <address_district>Śródmieście</address_district>
    <address_street>Al. Jerozolimskie</address_street>
    <address_building_number>65</address_building_number>
    <address_apartment_number></address_apartment_number>
    <postal_code>00-001</postal_code>
    <latitude>52.2297</latitude>
    <longitude>21.0122</longitude>
    <city>Warszawa</city>
    <transfer_ownership_date>2025-06-30</transfer_ownership_date>
    <website_url>https://inwestycja.pl</website_url>
    <monetary_benefits>5% cashback</monetary_benefits>
    <status>For sale</status>
    <investment_logo>https://demo1.voxdeveloper.com/files/investments/logo.png</investment_logo>
  </investment>
</xml>

2. Endpoint — List of units for an investment

URL (XML — default format):

GET https://demo1.voxdeveloper.com/webservice/realestatestatuslist/api_key/{API_KEY}/investment_id/{ID}

Example for the demo instance, XML (investment no. 15):
https://demo1.voxdeveloper.com/webservice/realestatestatuslist/api_key/ab33c2fb8240c8c7ca015d924713b5d234b7778e/investment_id/15

JSON version — the same endpoint returns data in JSON format after adding the /json/1 segment to the address:

GET https://demo1.voxdeveloper.com/webservice/realestatestatuslist/api_key/{API_KEY}/json/1/investment_id/{ID}

Example for the demo instance, JSON (investment no. 15):
https://demo1.voxdeveloper.com/webservice/realestatestatuslist/api_key/ab33c2fb8240c8c7ca015d924713b5d234b7778e/json/1/investment_id/15

Filtering results in the URL

The realestatestatuslist endpoint supports additional, optional filters passed in the URL. They allow you to reduce the size of the returned XML file — useful for large investments, where the full list of units loads slowly.

Rules for combining filters:

• The first segment in the address is investment_id or stage_id.
• Then, in any order, you can add type_id and/or status_id.
• Each of the type_id and status_id filters accepts a single value or a comma-separated list (CSV).

Examples of valid addresses:

# Only flats (type 1) in investment 15
.../realestatestatuslist/api_key/{API_KEY}/investment_id/15/type_id/1
# Flats and garages (types 1 and 2)
.../realestatestatuslist/api_key/{API_KEY}/investment_id/15/type_id/1,2
# Only available units (status 1)
.../realestatestatuslist/api_key/{API_KEY}/investment_id/15/status_id/1
# Flats available and with a verbal reservation (type 1, statuses 1 and 2)
.../realestatestatuslist/api_key/{API_KEY}/investment_id/15/type_id/1/status_id/1,2
# Filtering by stage instead of investment
.../realestatestatuslist/api_key/{API_KEY}/stage_id/15/type_id/1,2/status_id/1

Default fields (always returned)

Price fields (conditional)

Returned for available units (statuses 1, 2). If you want to display prices also for reserved or sold units — contact the administrator, who can enable the option "Add prices to xml when the status is unavailable". Completely disabling prices in the XML (e.g. at the developer's request) is also handled by the administrator.

Optional fields

These fields are visible in the XML only when the administrator has enabled them in the system configuration. They are grouped by topic — if you need a specific field, ask the administrator to enable it.

Additional prices:

Rental:

Areas and measurements:

Identifiers and naming:

Features and equipment:

Parking spaces, cellars, bicycle rooms:

Energy:

Additional dates and statuses:

Files:

Nested structures

They appear as separate elements inside <realestate>.

<contiguity_list> — appurtenances. Each <contiguity> contains:

<storey_list> — area breakdown into storeys / additional zones. A list of the unit's storeys and zones that are not main rooms (e.g. mezzanines, attics, lofts). The section appears after the "Apartment area" option is enabled (shared by <storey_list> and <room_list>). Each <storey> contains:

<room_list> — area breakdown into main rooms. A list of the unit's main rooms (e.g. rooms, kitchen, bathroom). The section appears after the "Apartment area" option is enabled (shared with <storey_list>). Each <room> contains:

<flags_list> — unit advantages / highlights. A list of features that distinguish the unit (e.g. "Balcony", "Corner window", "Park view"). The section appears after the "Advantages" option is enabled. Each <flag> contains:

XML example

<?xml version="1.0"?>
<xml>
  <realestate>
    <id>2041</id>
    <investment_id>15</investment_id>
    <investment_name>Test Investment</investment_name>
    <investment_status>For sale</investment_status>
    <investment_stage>Stage I</investment_stage>
    <building>A</building>
    <name>A - M1</name>
    <local_number>M1</local_number>
    <status_id>1</status_id>
    <status_name>Available</status_name>
    <area>45.50</area>
    <area_usable>38.20</area_usable>
    <rooms>2</rooms>
    <floor>3</floor>
    <completion_date>2025-06-15</completion_date>
    <ask_for_price>0</ask_for_price>
    <city>Warszawa</city>
    <price>490000.00</price>
    <pricemkw>10769.23</pricemkw>
    <price_net>453703.70</price_net>
    <pricemkw_net>9970.96</pricemkw_net>
    <date_modified>2025-05-26 17:00:00</date_modified>
    <type_id>1</type_id>
    <type>Flat</type>
    <balkon>8.50</balkon>
    <plan_link>https://demo1.voxdeveloper.com/files/realestate/plan.pdf</plan_link>
    <card_link>https://demo1.voxdeveloper.com/files/realestate/card.pdf</card_link>
    <contiguity_list>
      <contiguity>
        <contiguity_name>MP-12</contiguity_name>
        <contiguity_type>Parking space</contiguity_type>
        <contiguity_price>25000.00</contiguity_price>
        <contiguity_area>12.00</contiguity_area>
      </contiguity>
    </contiguity_list>
  </realestate>
</xml>

3. Endpoint — Price change history

You will find the link to the price history XML file of each unit in the price_change_history field of the previous endpoint. Example path:

https://demo1.voxdeveloper.com/files/price_changes/{hash1}/{hash2}.xml

The file is generated automatically after every price change — it requires no authorization other than knowing the URL. For convenience, a JSON version is also available (if the administrator has enabled it).

Fields always returned

Optional fields (enabled by the administrator)

Structure of <price_history>

It contains a list of <price_change> elements. Each contains:

XML example

<?xml version="1.0"?>
<xml>
  <realestate>
    <id>2041</id>
    <investment_id>15</investment_id>
    <investment_name>Test Investment</investment_name>
    <investment_stage>Stage I</investment_stage>
    <building>A</building>
    <name>A - M1</name>
    <local_number>M1</local_number>
    <type_id>1</type_id>
    <type>Flat</type>
    <price>490000.00</price>
    <price_net>453703.70</price_net>
    <pricemkw>10769.23</pricemkw>
    <pricemkw_net>9970.96</pricemkw_net>
    <price_history>
      <price_change>
        <date_modified>2025-05-26 17:00</date_modified>
        <type>List price</type>
        <before>
          <price>500000.00</price>
          <price_net>462962.96</price_net>
          <pricemkw>10989.01</pricemkw>
          <pricemkw_net>10175.01</pricemkw_net>
        </before>
        <after>
          <price>490000.00</price>
          <price_net>453703.70</price_net>
          <pricemkw>10769.23</pricemkw>
          <pricemkw_net>9970.96</pricemkw_net>
        </after>
      </price_change>
    </price_history>
  </realestate>
</xml>

4. Dictionaries: statuses, unit types and cardinal directions

Unit statuses

Unit types

Cardinal directions (the direction field)

The direction field in the XML describes the cardinal directions the unit faces. It can contain one or several comma-separated values (for corner / dual-aspect units).

The value format depends on a setting in the voxCRM panel — the option "Display an alternative list of cardinal directions (shortened Polish names, sorted clockwise)":

Full list of available codes (default variant — option disabled)

5. Integration examples

PHP — fetching a unit's status

<?php
// For the production environment, replace the API key and investment ID with your own.
function getRealEstateInfo(int $id): ?array {
    $url = 'https://demo1.voxdeveloper.com/webservice/realestatestatuslist'
         . '/api_key/ab33c2fb8240c8c7ca015d924713b5d234b7778e/investment_id/15';
    $xml = simplexml_load_file($url);
    if ($xml === false) {
        return null;
    }
    foreach ($xml->realestate as $realestate) {
        if ((int) $realestate->id === $id) {
            return [
                'id'          => (string) $realestate->id,
                'status_id'   => (int)    $realestate->status_id,
                'status_name' => (string) $realestate->status_name,
                'price'       => (float)  $realestate->price,
                'area'        => (float)  $realestate->area,
            ];
        }
    }
    return null;
}
$info = getRealEstateInfo(2041);
if ($info !== null) {
    echo "Unit #{$info['id']} — {$info['status_name']} — {$info['price']} PLN";
}

WordPress — shortcode with caching

<?php
/* Plugin Name: voxCRM Real Estate Table */
function voxcrm_realestate_table() {
    if (false === ($output = get_transient('voxcrm_realestate_table'))) {
        // For the production environment, replace the API key and investment ID with your own.
        $url = 'https://demo1.voxdeveloper.com/webservice/realestatestatuslist'
             . '/api_key/ab33c2fb8240c8c7ca015d924713b5d234b7778e/investment_id/15';
        $xml = simplexml_load_file($url);
        if ($xml === false) {
            return '<p>No data.</p>';
        }
        $output = '<table><thead><tr>'
                . '<th>Unit</th><th>Area</th><th>Status</th><th>Price</th>'
                . '</tr></thead><tbody>';
        foreach ($xml->realestate as $r) {
            $output .= sprintf(
                '<tr><td>%s</td><td>%s m²</td><td>%s</td><td>%s PLN</td></tr>',
                esc_html((string) $r->name),
                esc_html((string) $r->area),
                esc_html((string) $r->status_name),
                esc_html((string) $r->price)
            );
        }
        $output .= '</tbody></table>';
        set_transient('voxcrm_realestate_table', $output, HOUR_IN_SECONDS);
    }
    return $output;
}
add_shortcode('voxcrm_realestate_table', 'voxcrm_realestate_table');

Related materials

• How to retrieve a unit's price history data
• How to manage the information prospectus for submission to dane.gov.pl and to the website

6. Contact

If you have any questions or problems with the integration, please contact our technical support team:

• E-mail: kontakt@voxcommerce.pl
• Phone: 534 571 638

For matters related to the API key, the scope of shared investments and the visibility of optional fields — contact the administrator of your voxCRM instance.