Guide to synchronizing listings on Indomio

To automatically synchronize your listings with Indomio portals, you must create XML files (feeds) following the specifications described elsewhere in the documentation.

The feeds can be composed of a single listing and be sent to our REST service to be integrated in real-time (recommended choice), or be monolithic files to be synchronized daily in batch mode (obsolete).

REST API mode.

Based on REST-XML service is the most efficient solution to ensure data synchronization with Indomio almost in real time. You will be provided, by our Support team, with an account to use for authentication with the web service and you will have the ability to send listing updates at any time and without limits (even for the same listing several times a day) through the Indomio API. There is a trial period during which credentials from a test agency will be provided to allow smooth development of the call flow.

Authentication

Access to the endpoints is governed by authentication. Prior to activation you will need to communicate the public IPs of the servers from which REST calls will originate. Access each URL through HTTP BASIC authentication. Each call must then contain a username and password that will be provided to you by the Support team. Normally an additional header called X-IMMO-SOURCE is also required, Also provided along with the username.

Endpoint

Consult the swagger file for details and how to use it.

{···}

Write Payload.

Each write endpoint must be provided with a specific xml payload, consistent with the relevant section of the XSD schema. The schema itself is provided with explanatory annotation.

Your XML Document has to be sent to our REST entrypoint into the body of a PUT call.

Example:

PUT /ws/import/immobiliare/property/987654321

Other implementation details follow.

The XML document must meet these requirements:

• must pass XSD schema validation.
• must adopt the UTF-8 character encoding.

Removal Requests

In contrast to batch mode, with the REST API it is important to explicitly communicate the removal of listings from advertising. To do this requires an http call to the endpoint with method DELETE taking care to specify, at the end of the URL, the numeric portal identifier (receivable by /ServiceResponse/idListing, at the end of the write operations).

Example:

DELETE /ws/import/immobiliare/property/987654321

Endpoint responses

In compliance with the REST architecture each request corresponds, in response, to an HTTP status and an XML object called ServiceResponse containing an ErrorCode and other useful information. The following is an example. The order of the XML nodes is not guaranteed:

<ServiceResponse>
	<Result>true</Result>
	<EntityID>as-4fr5</EntityID>
	<EntityOwnerID>67012</EntityOwnerID>
	<RealEstate>someone@some.where</RealEstate>
	<ErrorCode>0</ErrorCode>
	<ErrorMessage>Success</ErrorMessage>
	<idListing>164578906</idListing>
	<lock>false</lock>
	<RequestID>3AA36B26-8771-45C5-9850-26EADEB13129</RequestID>
</ServiceResponse>

Meaning of the fields in the response message:

Name	Type	Mandatory	Description
Result	Boolean	Yes	Request outcome
EntityID	String	Yes	ID of the management system
EntityOwnerID	String	Yes	ID of the agency in the management system, if available
RealEstate	String	Yes	Agency username
ErrorCode	Integer	Yes	Status of request, see full list below for values
ErrorMessage	String	Yes	Error message for the request, if available
idListing	Integer	Yes	ID of the listing processed on Indomio.
lock	Boolean	Yes	Resource blocked if true. Listing is protected, agency can edit - or unlock - only from portal panel
RequestID	String	Yes	ID of the request, unique
ListingUuid	String	No	UUID of the listing
AgencyUuid	String	No	UUID of the agency
RealtorId	Integer	No	ID of the agent (on the portal)
RealtorUuid	String	No	UUID of the processed agent
RealtorExternalId	String	No	ID of the agent in the management system

The outcome of each request consists of a standard HTTP STATUS and an ErrorCode that elaborates on the source of the error:

ErrorCode	Name	Description
0	SUCCESS	Operation terminated successfully
330	OFFLINE_RE	Agency Offline
400	BAD_REQUEST	Feed not validated or incompatible or incorrect data.
401	WRONG_STATUS	Listing rejected due to a status issue (usually agency related)
403	LOCKED	Protected resource
404	NOT_FOUND	Resource not found
409	ID_MISMATCH	ID format error.
422	AGENCY_PHONE_NUMBER_NOT_UPDATABLE	agencies only attempt to update a phone number associated with an external service
440	MISSING_FIELD	Required field absent
445	MISSING_REALTOR	Agents only Unable to find agent
450	MISSING_RE	Unable to find agency
455	UNRESOLVED_TYPOLOGY	Listing only Property type not found or not associated
460	MISSING_GEO	Inconsistent geographic information
470	BAD_JAXB_REQUEST	XSD validation failed
480	UNKNOWN_CMD	Unknown @operation attribute
500	GENERIC_ERROR	Generic error

Batch mode

Payload

The payload is identical in both real-time and batch modes; in fact, they share the same XSD schema.

We will address some critical discriminants without going into detail. For timely documentation of the nodes we refer to the full paper, remembering that the annotations in the XSD can also help you in your development.

The following examples are either applied to a property object or are XML fragments of the same.

Identifiers

To synchronize a resource, it is necessary to uniquely identify it. You can take one approach among those available to do this:

Entity	XPath	Description	Mandatory
Listing	//property/unique-id	Used to identify the listing paired with the username (email) of the agency	Yes
Company	//property/agent/email	Agency username	Yes
Realtor	//property/agent/realtors/realtor/id	Identifier of the agent on the portal	No

Example:

<property operation="write">
  <unique-id><![CDATA[123456]]></unique-id>
  ...
  <agent>
    <office-name><![CDATA[Agenzia Test]]></office-name>
    <email>agency-email@example.com</email>
  </agent>
  ...
</property>

Last-updated

The last-updated field is critical for assessing the actual need to update a listing. If the date on our DB is greater than or equal to the date in the feed we will not update the listing. This approach allows us to contain the operational load of the import processes and is non-negotiable.

All dates must be submitted in ISO-DATE-TIME format, here is an example:

<property operation="write">
  ...
  <date-updated>2019-10-10T12:00:12</date-updated>
  ...
</property>

Property Type

Each property must have an associated property type. The typology is sent in the form of a numeric identifier as in the example:

<building IDType="14" />

You can access the detailed list of supported typologies. Remember also that there are rules that some typologies are not always applicable (e.g., a room for sale).

Price and contract type

Each listing must have a R (Rent) or S (Sale) contract, the //transaction/@type element is mandatory.

In //transaction/price, you can define the sale price, which can be hidden by associating the value true with the attribute //transaction/price/@reserved.

<transactions>
    <transaction type="S">
      <price currency="EUR" reserved="false">140000</price>
    </transaction>
</transactions>

Note also the //transaction/price/@currency attribute. We currently support only the Euro currency (EUR).

Geography

Each property must be located geographically. The best system is to define its geographic coordinates (latitude and longitude). Pair them with the country code and address.

In the absence of geographic coordinates, it becomes essential to define the city. The attribute //location/city/@code contains the ISTAT code of the municipality.

  <location>
    <country-code>IT</country-code>
    <administrative-area>Marche</administrative-area>
    <sub-administrative-area>Ancona</sub-administrative-area>
    <city code="042021">Jesi</city>
    <locality map="exact">
      <postal-code>60035</postal-code>
      <latitude>43.5176</latitude>
      <longitude>13.2506</longitude>
      <thoroughfare display="yes"><![CDATA[Via Marconi, 292]]></thoroughfare>
    </locality>
  </location>

Thanks to the //location/locality/@map attribute, it is also possible to obfuscate the exact geographic location.

Media

Each listing can be accompanied by a set of images, floor plans, documents, and virtual tours. Each media must be accessible through an external URL, you can define the order in which to display the media with the @position attribute as in this example:

  <pictures>
    <picture position="1" url="http://s3-eu-central-1.amazonaws.com/1053424_thumb_109-2012-454_1053424.jpg"/>
    <picture position="2" url="http://s3-eu-central-1.amazonaws.com/1053425_thumb_109-2012-454_1053425.jpg"/>
    <picture position="3" url="http://s3-eu-central-1.amazonaws.com/1053426_thumb_109-2012-454_1053426.jpg"/>
    <picture position="4" url="http://s3-eu-central-1.amazonaws.com/1053427_thumb_109-2012-454_1053427.jpg"/>
    <picture position="5" url="http://s3-eu-central-1.amazonaws.com/1053428_thumb_109-2012-454_1053428.jpg"/>
  </pictures>

Max image size is 5 242 880 byte (about 5.2 Mb).

Images and other media are delegated to an asynchronous download system. Even with positive response to a Real-time system call, the media update is subject to a wait of several minutes.

It is good that the servers hosting the images accept HEAD calls; this system is used to verify that it is really necessary to update a resource.

Premium and Extra-Visibility

It is possible to control from flow the extra-visibility of a listing. This is done by adopting the //publish node as follows:

<publish>
    <portal id="immobiliare.it" status="true">
      <visibilities>
        <visibility op="active">premium</visibility>
        <visibility op="active">top</visibility>
        <visibility op="remove">showcase</visibility>
      </visibilities>
    </portal>
  </publish>

In the example we ask to activate premium and top visibility, if active the star visibility will also be revoked.

Requests of this kind can be rejected if the agency does not have permissions to set extra-visibilities or if it has exhausted the available ceiling.

Calls without the //publish node, or with partial content, leave the existing situation unchanged.

---

2025 Indomio.com

• REST API mode.
  • Authentication
  • Endpoint
  • Endpoint responses
• Batch mode
• Payload
  • Identifiers
  • Last-updated
  • Property Type
  • Price and contract type
  • Geography
  • Media
  • Premium and Extra-Visibility