Version 2.20
January, 2021

INTRODUCTION

The Domibus Send Data System is organized around REST. Domibus SDS uses predictable, resource-oriented URLs, and uses HTTP POST requests. We support cross-origin resource sharing, allowing you to recieve data securely with our SDS from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is sent by all our requests.

This section of the documentation is geared towards developers.

REST Request - how to send a request including the domains, paths, and HTTP Method conventions we use. Also includes how to authenticate yourself.

REST Response - we have a standard response wrapped, which is detailed here. We also talk about HTTP status codes and how we return error messages.

REQUESTS

Using SSL

All requests should be called over SSL. You must use SSL when working with non-public data such as customer accounts and private information. Make sure your client/server technology supports SSL.

Data Types

Array Inputs

JSON Payloads Data is returned using JSON (Javascript Object Notation). JSON is the only format we support. It's a lightweight serialization language that is compatible with many different programming languages and technologies. JSON is syntactically correct JavaScript code, meaning you can use the Javascript eval() function to parse it.

HTTP Methods

All requests will be sent via HTTP POST, since we will be sending/creating one or more resources. However, some operation require other HTTP methods:

HTTP Method	Description
GET	Reads resources via URL, often with query string criteria
POST	Create a new resource.
PATCH	Updates an existing resource.

Authentication

Your Partner Token is provided by Domibus. Token API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to your API/Webhook is performed via HTTP Shared User Token.

Each POST request needs to contain information that identifies you as the client and the agent/office.

The following variables will be included in all POST calls:

• Authorization: Bearer which is the Partner Token sent in the header. (using the parameter Authorization: Bearer TOKEN)
• agent_id which is sent as a POST variable. (Given by you in order to identify the user/agent sending real estate information)
• agent_token which is sent as a POST variable. (Given by you in order to identify the user/agent sending real estate information)

POST Request parameters V.2 (coded)

Parameter	Value	Description
agent_id	String	The identifier of the user sending data.
agent_token	String	The token identifier of the user sending data.
reference	Int	The reference of the property.
prospect	Bool	Is it a prospect?
operacion_type	Int	The type of operation being offered. Values: ('for sale'=>1,'for rent'=>2)
price	Int	The price of the property.
property_type	Int	The type of property being offered. Values ES: ('Loft'=>3299, 'Estudio'=>3099, 'Estudios'=>3099, 'Apartamentos'=>2799, 'Apartamento'=>2799, 'Piso'=>3399, 'Pisos'=>3399, 'Atico'=>4799, 'Aticos'=>4799, 'Bajo'=>3499, 'Buhardilla'=>4699, 'plantas bajas'=>3499, 'Planta baja'=>3499, 'Plantas bajas'=>3499, 'Vivienda'=>3399, 'Chalet'=>499,'chalet'=>499,'Chalet adosado'=>199,'Chalet pareado'=>999, 'Casa'=>399,'Casa de pueblo'=>6299,'Casa o chalet independiente'=>399,'Casa adosada'=>399,'Casa rural'=>11699,'Casa terrera'=>6599, 'Caserón'=>6099, 'Caseron'=>6099, 'Cortijo'=>599, 'Masia'=>599, 'Masias'=>599, 'Masía'=>599, 'Masías'=>599, 'Finca rustica'=>3699, 'Castillo'=>5699, 'Castillos'=>5699, 'Torre'=>1099, 'Torres'=>1099,'Mansion / palacio'=>5699, 'Palacio'=>5699, 'Palacios'=>5699, 'Pueblo'=>4999, 'Pueblos'=>4999, 'Villa'=>4999, 'Villas'=>4999, 'Duplex'=>2999, 'Bungalow'=>299, 'Triplex'=>2999, 'Oficina'=>1399, 'Local'=>1299, 'Local o nave'=>1299, 'Almacén'=>1599, 'Nave'=>2099, 'Nave industrial'=>2099, 'Garaje'=>2399, 'Trastero'=>2699, 'Terreno'=>4099, 'Edificio'=>1699)
country	String	The country code where the property is located. Values: ('Spain'=>'es','France'=>'fr','Italy'=>'it')
provence	Int	The provence where the property is located. Values: localities_es.json
locality	Int	The locality where the property is located. Values: localities_es.json
street	String	The street where the property is located.
street_number	String	The street number where the property is located.
lat	Float	The lattude where the property is located.
lng	Float	The longitude where the property is located.
bedroom	Int	The number of rooms on the property.
wc	Int	The number of bathrooms on the property.
m2	Int	The area of the property.
m2_terrain	Int	The area of the terrain of property.
origin	String	The origin website of the property.
url	String	The url of the property.
description	String	The description of the property.
tags	String List	The list of features on the property.
handicapped_acc	Bool	There is handicapped access.
water	Bool	There is water.
central_air	Bool	There is central air.
air_conditioning	Bool	There is air conditioning.
alarm	Bool	There is alarm.
fire_alarm	Bool	There is fire alarm.
theft_tlarm	Bool	There is theft tlarm.
separate_apartment	Bool	There is separate apartment.
trees	Bool	There is trees.
builtin_cabinet	Bool	There is builtin cabinet.
elevator	Bool	There is elevator.
balcony	Bool	There is balcony.
bar	Bool	There is bar.
barbecue	Bool	There is barbecue.
attic	Bool	There is attic.
safe	Bool	There is safe.
heating	Bool	There is heating.
central_heating	Bool	There is central heating.
shopping_mall	Bool	There is shopping mall.
fireplace	Bool	There is fireplace.
kitchen_type	Int	Kitchen type. Values: ('office'=>1,'independent'=>2)
conservation	Int	Conservation. Values ES: ('Para reformar'=>5, 'De origen'=>10, 'Reformar Parcialmente'=>15, 'Entrar a vivir'=>20, 'Buen estado'=>30, 'Semireformado'=>40, 'Reformado'=>50, 'Seminuevo'=>60, 'Nuevo'=>70,'Obra Nueva'=>80,'En construcción'=>90, 'En proyecto'=>100)
community_fees_incl	Bool	It is community fees included.
water_tank	Bool	There is water tank.
water_softener	Bool	There is water softener.
pantry	Bool	There is pantry.
diaphanous	Bool	Itis diaphanous.
gallery	Bool	There is gallery.
double_garage	Bool	There is double garage.
city_gas	Bool	There is city gas.
gym	Bool	There is gym.
playroom	Bool	There is playroom.
hydromassage	Bool	There is hydromassage.
piped_music	Bool	There is piped music.
jacuzzi	Bool	There is jacuzzi.
garden	Bool	There is garden.
orientation_key	Int	Orientation key. Value: ('None'=>0, 'North'=>1, 'South'=>2, 'East'=>3, 'West'=>4, 'Northwest'=>5, 'Southwest'=>6, 'East, West'=>7, 'Southeast'=>8, 'North, South'=>9, 'Northeast'=>10)
laundry	Bool	There is laundry.
telephone_l	Bool	There is telephone line.
luminous	Bool	It is luminous.
electricity	Bool	There is electricity.
viewpoint	Bool	There is viewpoint.
forklift	Bool	There is forklift.
furniture	Bool	There is furniture.
portholes	Bool	There is portholes.
option_to_buy	Bool	There is option to buy.
courtyard	Bool	There is courtyard.
pergola	Bool	There is pergola.
com_swimming_pool	Bool	There is community swimming pool.
priv_swimming_pool	Bool	There is private swimming pool.
floor	Int	Floor number. Value: ('Floor 0'=>0,'Floor 2'=>2,'Floor 3'=>3,'Floor 4'=>4,'Floor 5'=>5,...)
garage	Bool	There is garage.
preinst_air_conditioning	Bool	There is preinstallation for air conditioning.
preinst_piped_music	Bool	There is preinstallation for piped music.
beachfront	Bool	There is beachfront.
automatic_doors	Bool	There is automatic doors.
armored_door	Bool	There is armored door.
automatic_irrigation	Bool	There is automatic irrigation.
satellite	Bool	There is satellite.
sauna	Bool	There is sauna.
solarium	Bool	There is solarium.
basement	Bool	There is basement.
priv_tennis_court	Bool	There is private tennis court.
com_tennis_court	Bool	There is community tennis court.
terrace	Bool	There is terrace.
glazed_terrace	Bool	There is glazed terrace.
all_exterior	Bool	Itis all exterior.
storage_room	Bool	There is storage room.
three_phase	Bool	There is three phase power.
tv	Bool	There is tv.
fencing	Bool	There is fencing.
changing_room	Bool	There is changing room.
video_intercom	Bool	There is video intercom.
sea_views	Bool	There is sea views.
children_area	Bool	There is children area.
status	Int	The prospect status of the property. Values: ('Pending'=>1,'Contacted'=>2,'Prospected'=>3,'Do Not Contact'=>4,'Not Available'=>5)
first_name	String	The prospect first name of the property.
last_name	String	The prospect last name of the property.
phone	String	The prospect phone of the property.
phone_alt	String	The prospect phone alternative of the property.
email	String	The prospect email of the property.
observations	String	The prospect observations of the property.

RESPONSE

Response Formats

All responses must be returned using JSON. JSON is a lightweight serialization language that is compatible with many different languages. JSON is syntactically correct JavaScript code, meaning you can use the Javascript eval() function to parse it.

HTTP Status Codes

Standard HTTP status codes must be used to indicate success or failure of the calls. Like with most topics, Wikipedia has good resources on HTTP Statuses, but here are the basics of what we will return:

HTTP Code	Message	Description
200	OK	The request was processed and returned successfully. Nothing was changed.
201	Created	The new resource was created successfully
400	Bad Request	Problem with the request, such as a missing, invalid or type mismatched parameter
401	Unauthorized	The request did not have valid authorization credentials
403	Forbidden	Private data you are not allowed to access.
404	Not Found	Your URL is wrong, or the requested resource doesn't exist
429	Too Many Requests	You've hit a rate limit.
500	Server Error	We call this the "crap code" error. Basically we've got a problem on our side. If this persists please contact support. We log and review all errors but your help often helps us fix it quicker.
503	Service Unavailable	Our API is down. Please try again. We work hard to make this rare.

The non-20x status codes above correspond with an error of one type or another.

Errors

Errors are communicated to the client in the payload of the response.

Errors in the Response Payload

The standard response payload can contain errors. This will give more finely grained details about specific what caused the error or errors, which should allow you to respond appropriately. This might include displaying validation messages to your users, or changing the request at runtime.

Example:

{
"code": "rest_no_route",
"message": "No route was found matching the URL and request method",
"status": 404
}

Error Type Definition

The errors have the following data definition:

Name	Type	Description
code	String	Error code. Unique string identifying the type of error. See the table below for a list of possible error codes. (Always returned)
message	String	Localized user readable message describing the error. (This will be shown to the end user)
status	Int	The HTTP code.

Response Payload

Each API response is wrapped in a standard payload that contains the results of the call, plus some additional useful information and metadata.

Name	Type	Description
code	String	Determines the code of the message.
message	String	An explanatory description about the response. (This will be shown to the end user)
status	Int	The HTTP code.

Here's an example of a response:

{
"code": "ok",
"message": "All good",
"status": 200
}