Domibus API v2

Version 2.2
June , 2017

INTRODUCTION

The Domibus API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We support cross-origin resource sharing, allowing you to interact securely with our API 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 returned by all API responses, including errors.

This section of the documentation is geared towards developers and covers the basics of using any of our REST APIs.

REST Request - how to send a request including the domains, paths, and HTTP Method conventions we use. Also includes how to authenticate yourself and details on the common parameters for pagination, filtering and sorting.

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 API methods 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 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

The majority of calls to the API will be via HTTP GET, since you will be requesting 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 API keys are provided by Domibus. Your 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 the API is performed via HTTP Shared User Token.

Each request needs to contain information that identifies you as the client.

All calls to the API require the authentication module to be invoked. The following variables must be included in all API calls:

client

params

There are two methods of authentication that can be chosen from though the use of the variable auth (Defaults to 2 when not defined).

  • auth = 1 (forces the API to use the Basic Authentication method)
  • auth = 2 (forces the API to use the Advances Authentication method)

Basic Authentication

Basis authentication utilizes the variables:

  • client which is sent as a URL parameter.
  • params which is sent in the header (using the parameter Authorization = params). params is formed by encapsulating in JSON format the variables api_key (token) and the user (which correspond to a user name in you system).

Authentication happens in every call against our API by adding both the variable client and params.

PHP Example:

<?php
$client="client123";		//client id (provided by us)
$api_key = 'abcde123456';	//do not send this to the API endpoint (provided by us)

$params['user']="apitest";
$params['token']=$api_key;
$params=json_encode( $params );
...

Avanced Authentication

Advanced authentication utilizes the variables:

  • client which is sent as a URL parameter.
  • params which is sent in the header (using the parameter Authorization = params). params is formed by encapsulating in JSON format the variables token and the user (which correspond to a user name in you system).
    The encapsulated JSON contains the sensitive variables that shouldn't be visible in a URL (
    user and token are mandatory) and (company_number, email, etc are optional during user account manipulation). This is accomplished by encrypting using openssl_encrypt with an AES-128-ECB algorithm and the same api_key.

    • The token is a hashed generated by concatenating the client+user and the specified key (api_key) using the HMAC method and a sha512 hash algorithm.

Authentication happens in every call against our API by adding both the variable client and params.

PHP Example:

<?php
$client="client123";		//client id (provided by us)
$api_key = 'abcde123456';	//do not send this to the API endpoint (provided by us)

//encripted variables to be sent
$params['user']="apitest";	//user id (given by your login system)
$params['token']=base64_encode(hash_hmac('sha512', $client.$user, $api_key, TRUE));
$params=openssl_encrypt(json_encode( $params ),"AES-128-ECB",$api_key);
...

Request Responses

Our API servers reside at:

https://www.domibus.com/api/

You make requests to a URL that have the following patterns:

https://www.domibus.com/api/rest/v2/{some resource path}

Property Listing, Searching and Sorting

Searching for data offers very flexible options for inputs as well as sorting. Below are the options you can specify when searching.

Available Endpoints

GET property by ID:

/rest/v2/property/(?P<id>\d+)

https://www.domibus.com/api/rest/v2/property/12345

GET property by Province or map:

/rest/v2/property/(?P<search_type>\w+)/(?P<offer>\w+)/(?P<property>\w+)

https://www.domibus.com/api/rest/v2/property/prov/venta/viviendas?client=clientid&params=tokenicedparams&province=valencia

Available Parameters

Parameter Value Description
client String The identifier of the client company (Mandatory)
params String JSON encoded variables that will be OpenSSL encrypted and passed as a hashed string. (Mandatory)
user The identifier of the user from the client company (Mandatory)
token Is a hash provided by the Authentication script (Mandatory)
search_type String Determines the type of seach that will be conducted by the API. (Optional)

Values:

('map'=>'Búsqueda por mapa', 'prov'=>'Búsqueda por provincia')

offer String Is the type of property transaction being offered.

(Mandatory when search_type=”prov”or”map”)

Values:

('venta'=>'Venta', 'alquiler'=>'Alquiler')

property String Is the type of property being offered.

(Mandatory when search_type=”prov”or”map”)

Values:

('viviendas'=>'Viviendas', 'oficinas'=>'Oficinas', 'locales_naves'=>'Locales Naves', 'garajes'=>'Garajes', 'terrenos'=>'Terrenos')

province String Provinces of the country. (Mandatory when search_type=”prov”)
coord String The coordinates resulting from a google map polygon area. It requires a minimum of three (3) coordinate points.

(Mandatory when search_type=”map”)

Format:

(lat1, lng1)^(lat2, lng2)^(lat3, lng3)...

locality String Localities within each Province. (Optional)
id Int The reference ID of a property. (Mandatory when no search_type is set)
pmin Int The minimum price. (Optional)
pmax Int The maximum price. (Optional)
tmin Int The minimum size in square meters (m2). (Optional)
tmax Int The maximum size in square meters (m2). (Optional)
property_subtype String The sub category of property. (Optional)

It allows multiple values in the same request.

Values when property=”viviendas”:

('piso'=>'Pisos', 'chalet'=>'Casas o Chalets', 'casa'=>'Casas rústicas', 'atico'=>'Áticos', 'duplex'=>'Dúplex')


Values when
property=”local_naves”:
('local'=>'Local', 'nNave'=>'Nave')


Values when
property=”terreno”:
('urbano'=>'Urbano', 'urbanizable'=>'Urbanizable', 'nourbanizable'=>'No urbanizable')

Format:

piso^chalet...

rooms Int The number of rooms. (Optional)

It allows multiple values in the same request.

Values:

('1'=>'1 baño', '2'=>'2 baños', '3'=>'3 baños', '4'=>'4 baños o más')

Format:

1^2...

wc Int The number of bathrooms. (Optional)

It allows multiple values in the same request.

Values:

('1'=>'1 baño', '2'=>'2 baños', '3'=>'3 baños', '4'=>'4 baños o más')

Format:

1^2...

attributes String The additional attributes associated with a property. (Optional)

It allows multiple values in the same request.

Values when property=”viviendas”:

('ascen'=>'Con Ascensor', 'garaje'=>'Garaje', 'piscina'=>'Piscina', 'terraza'=>'Terraza', 'jardin'=>'Jardín', 'trast'=>'Trastero', 'playa'=>'Playa', 'aempotrado'=>'Empotrados', 'calef'=>'Calefacción', 'aircond'=>'Aire acondicionado', 'vigil'=>'Vigilancia', 'ornorte'=>'Orientación Norte', 'orsur'=>'Orientación Sur', 'oreste'=>'Orientación Este', 'oroeste'=>'Orientación Oeste')


Values when
property=”local_naves”:
('ccomercial'=>'En centro comercial', 'piecalle'=>'A pie de calle', 'entreplanta'=>'Entreplanta', 'subterraneo'=>'Subterráneo', 'calef'=>'Calefacción', 'esquina'=>'Hace esquina', 'aircond'=>'Aire acondicionado', 'humos'=>'Salida de humos')


Values when
property=”terreno”:
('accviaurbana'=>'Acceso via urbana', 'accporcarr'=>'Acceso por carretera', 'accporcam'=>'Acceso por camino', 'agua'=>'Agua', 'alectric'=>'Electricidad', 'alcant'=>'Alcantarillado', 'gasnat'=>'Gas natural', 'alumpub'=>'Alumbrado público', 'acera'=>'Aceras')

Values when property=”oficinas”:

('diaf'=>'Diáfana', 'tabicada'=>'Tabicada', 'mamparas'=>'Mamparas', 'Uexclusivo'=>'Uso exclusivo', 'umixto'=>'Uso mixto', 'ascen'=>'Con Ascensor', 'garaje'=>'Garaje', 'Acaliente'=>'Agua caliente', 'calef'=>'Calefacción', 'aircond'=>'Aire acondicionado', 'vigil'=>'Vigilancia')

Values when property=”garaje”:

('ascen'=>'Con Ascensor', 'cubierta'=>'Cubierta', 'trast'=>'Trastero', 'vigil'=>'Vigilancia', 'pautomatica'=>'Puerta automática', 'moto'=>'Plaza para moto')

Format:

ascen^garaje^aircond...

timeframe String The time-frame looking back that the data is pulled from. (Optional)

Values:

('dia'=>'Últimas 24 horas', '48'=>'Últimas 48 horas', 'semana'=>'La última semana', 'mes'=>'El último mes')

order String The order in which the data is displayed. (Optional)

Values:

('recientes'=>'Recientes', 'antiguos'=>'Antiguos', 'baratos'=>'Baratos', 'caros'=>'Caros')

provider String The provider the data was original obtained from. (Optional)

Values:

Check with Domibus Support Team

page Int The page to display from the total of pages resulting from the data obtained. (Optional)

Defaults to “1”.

items_per_page Int The number (between “1” and “20”) of items to be displayed per page. (Optional)

Defaults to “20”.

acquired Int This value indicates properties that have been acquired by the user. (Optional)

Values:

1” (Show only Acquired), “0” (Show All)

Defaults to “0”

To help control the quantity of response data returned in a call, we support page and items_per_page request parameters. The majority of calls to the API will allow for the use of pagination since you will be requesting one or more resources.

For example, you can fetch the first 20 results by setting page to 1 and items_per_page to 20. To fetch the second 20 results, set page to 2 and items_per_page to 20.

You can tell how many results matched your query by looking at the total property that is returned in every response back from the API.

Examples

PHP Example with Basic Authentication:

&lt;?php
$client="client123";		//client id (provided by us)
$api_key = 'abcde123456';	//do not send this to the API endpoint (provided by us)

$params['user']="apitest";
$params['token']=$api_key;
$params=json_encode( $params );
$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL =&gt; "https://www.domibus.com/api/rest/v2/property/1000331?auth=1&amp;client=".$client,
CURLOPT_RETURNTRANSFER =&gt; true,
CURLOPT_ENCODING =&gt; "",
CURLOPT_MAXREDIRS =&gt; 10,
CURLOPT_TIMEOUT =&gt; 30,
CURLOPT_HTTP_VERSION =&gt; CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST =&gt; "GET",
CURLOPT_POSTFIELDS =&gt; "",
CURLOPT_HTTPHEADER =&gt; array(
"authorization: ".$params."",
"content-type: application/json"
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

PHP Example with Advanced Authentication:

&lt;?php
$client="client123";		//client id (provided by us)
$api_key = 'abcde123456';	//do not send this to the API endpoint (provided by us)

//encripted variables to be sent
$params['user']="apitest";	//user id (given by your login system)
$params['token']=base64_encode(hash_hmac('sha512', $client.$user, $api_key, TRUE));
$params=openssl_encrypt(json_encode( $params ),"AES-128-ECB",$api_key);

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL =&gt; "https://www.domibus.com/api/rest/v2/property/1000331?auth=2&amp;client=".$client,
CURLOPT_RETURNTRANSFER =&gt; true,
CURLOPT_ENCODING =&gt; "",
CURLOPT_MAXREDIRS =&gt; 10,
CURLOPT_TIMEOUT =&gt; 30,
CURLOPT_HTTP_VERSION =&gt; CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST =&gt; "GET",
CURLOPT_POSTFIELDS =&gt; "",
CURLOPT_HTTPHEADER =&gt; array(
"authorization: ".$params."",
"content-type: application/json"
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

Access Data Source Information

This type of request is designed to obtain the source URL that the property was originally acquired from to be able to view the contact information of the property owner at its source.

Available Endpoints

GET access by ID:

/rest/v2/access/(?P<id>\d+)

https://www.domibus.com/api/rest/v2/access/12345

Available Parameters

Parameter Value Description
id Int The reference ID of a property. (Mandatory)

Examples

PHP Example with Advanced Authentication:

&lt;?php
$client="client123";		//client id (provided by us)
$api_key = 'abcde123456';	//do not send this to the API endpoint (provided by us)

//encripted variables to be sent
$params['user']="apitest";	//user id (given by your login system)
$params['token']=base64_encode(hash_hmac('sha512', $client.$user, $api_key, TRUE));
$params=openssl_encrypt(json_encode( $params ),"AES-128-ECB",$api_key);

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL =&gt; "https://www.domibus.com/api/rest/v2/access/900234?client=".$client,
CURLOPT_RETURNTRANSFER =&gt; true,
CURLOPT_ENCODING =&gt; "",
CURLOPT_MAXREDIRS =&gt; 10,
CURLOPT_TIMEOUT =&gt; 30,
CURLOPT_HTTP_VERSION =&gt; CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST =&gt; "GET",
CURLOPT_POSTFIELDS =&gt; "",
CURLOPT_COOKIE =&gt; "wfvt_1492410860=591977b3ed37a",
CURLOPT_HTTPHEADER =&gt; array(
"authorization: ".$params,
"content-type: application/json"
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

Alerts Management

*This type of request is used exclusively in partial API integrations that utilize a Domibus Landing Page. It is designed to obtain or process Alerts created in the Domibus platform.

Available Endpoints

GET alert by ID:

/rest/v2/alert/(?P<id>\d+)

https://www.domibus.com/api/rest/v2/alert/12345

GET alert by user:

/rest/v2/alert

https://www.domibus.com/api/rest/v2/alert

Available Parameters

Parameter Value Description
id Int The reference ID of an alert. (Optional)
action String Determines if we want to get information about the alert or process the alert. (Optional)
Values:('list'=>'get information about alert', 'process'=>'process alert')
Defaults to “'list'”.

Examples

PHP Example with no action specified:

&lt;?php
$client="client123";		//client id (provided by us)
$api_key = 'abcde123456';	//do not send this to the API endpoint (provided by us)

//encripted variables to be sent
$params['user']="apitest";	//user id (given by your login system)
$params['token']=base64_encode(hash_hmac('sha512', $client.$user, $api_key, TRUE));
$params=openssl_encrypt(json_encode( $params ),"AES-128-ECB",$api_key);

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL =&gt; "https://www.domibus.com/api/rest/v2/alert/900234?client=".$client,
CURLOPT_RETURNTRANSFER =&gt; true,
CURLOPT_ENCODING =&gt; "",
CURLOPT_MAXREDIRS =&gt; 10,
CURLOPT_TIMEOUT =&gt; 30,
CURLOPT_HTTP_VERSION =&gt; CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST =&gt; "GET",
CURLOPT_POSTFIELDS =&gt; "",
CURLOPT_COOKIE =&gt; "wfvt_1492410860=591977b3ed37a",
CURLOPT_HTTPHEADER =&gt; array(
"authorization: ".$params,
"content-type: application/json"
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

PHP Example with action=”process:”

&lt;?php
$client="client123";		//client id (provided by us)
$api_key = 'abcde123456';	//do not send this to the API endpoint (provided by us)

//encripted variables to be sent
$params['user']="apitest";	//user id (given by your login system)
$params['token']=base64_encode(hash_hmac('sha512', $client.$user, $api_key, TRUE));
$params=openssl_encrypt(json_encode( $params ),"AES-128-ECB",$api_key);

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL =&gt; "https://www.domibus.com/api/rest/v2/alert/900234?client=".$client."&amp;action=process",
CURLOPT_RETURNTRANSFER =&gt; true,
CURLOPT_ENCODING =&gt; "",
CURLOPT_MAXREDIRS =&gt; 10,
CURLOPT_TIMEOUT =&gt; 30,
CURLOPT_HTTP_VERSION =&gt; CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST =&gt; "GET",
CURLOPT_POSTFIELDS =&gt; "",
CURLOPT_COOKIE =&gt; "wfvt_1492410860=591977b3ed37a",
CURLOPT_HTTPHEADER =&gt; array(
"authorization: ".$params,
"content-type: application/json"
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

User Management

This section covers the methods available to view, create and update users within your subscription. It also covers the methods to either upgrade or downgrade a user subscription.

Available Endpoints

GET (view) current user:

/rest/v2/user/

https://www.domibus.com/api/rest/v2/user/

POST (create) user:

/rest/v2/user/

https://www.domibus.com/api/rest/v2/user/

PATCH (update) current user:

/rest/v2/user/

https://www.domibus.com/api/rest/v2/user/

Available Parameters

Parameter Value Description
client String The identifier of the client company (Mandatory)
action String Is the action available (Optional when using the method GET)

Values:

('login'=>'login', 'upgrade'=>'upgrade', 'downgrade'=>'downgrade')

*login is limited to partial API integrations that utilize a Domibus Landing Page.

params String JSON encoded variables that will be OpenSSL encrypted and passed as a hashed string. (Mandatory)
user The identifier of the user from the client company (Mandatory)
token Is a hash provided by the Authentication script (Mandatory)
first_name (Optional when using the methods POST/PATCH)
last_name (Optional when using the methods POST/PATCH)
subscription (Optional when using the methods POST/PATCH)

Values:

('demo'=>'demo', 'ilimitata'=>'ilimitata')

email (Optional when using the methods POST/PATCH)
company_name (Optional when using the methods POST/PATCH)
company_number (Optional when using the methods POST/PATCH)
phone (Optional when using the methods POST/PATCH)
address_street (Optional when using the methods POST/PATCH)
address_city (Optional when using the methods POST/PATCH)
address_state (Optional when using the methods POST/PATCH)
address_postalcod (Optional when using the methods POST/PATCH)
address_country (Optional when using the methods POST/PATCH)
agreement (Optional when using the methods POST/PATCH)

Values:

('0'=>'0', '1'=>'1')

Examples

PHP Example with GET Method:

&lt;?php
$client="client123";		//client id (provided by us)
$api_key = 'abcde123456';	//do not send this to the API endpoint (provided by us)

$params['user']="apitest";
$params['token']			=base64_encode(hash_hmac('sha512', $client.$user, $api_key, TRUE));
$params				=openssl_encrypt(json_encode( $params ),"AES-128-ECB",$api_key);

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL =&gt; "https://www.domibus.com/api/rest/v2/user/?client=".$client,
CURLOPT_RETURNTRANSFER =&gt; true,
CURLOPT_ENCODING =&gt; "",
CURLOPT_MAXREDIRS =&gt; 10,
CURLOPT_TIMEOUT =&gt; 30,
CURLOPT_HTTP_VERSION =&gt; CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST =&gt; "GET",
CURLOPT_POSTFIELDS =&gt; "",
CURLOPT_HTTPHEADER =&gt; array(
"authorization: ".$params."",
"content-type: application/json"
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

PHP Example with POST Method:

&lt;?php
$client				="client123";		//client id (provided by us)
$api_key 			= 'abcde123456';	//do not send this to the API endpoint (provided by us)

//encripted variables to be sent
$params['user']			="apitest";	//user id (given by your login system)
$params['subscription']		= 'demo';
$params['email']   		= 'myemail@mydomain.com';
$params['first_name']		= 'apitest firstn';
$params['last_name']		= 'apitest lastn';
$params['company_name']	= 'apitest LLC';
$params['company_number']	= 'CNUM123456';
$params['phone']		= '123456789';
$params['address_street']	= 'apitest adress';
$params['address_city']		= 'apitest city';
$params['address_state']		= 'Madrid';
$params['address_postalcod']	= 'apitest postalc';
$params['address_country']	= 'apitest country';
$params['token']			=base64_encode(hash_hmac('sha512', $client.$user, $api_key, TRUE));
$params				=openssl_encrypt(json_encode( $params ),"AES-128-ECB",$api_key);

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL =&gt; "https://www.domibus.com/api/rest/v2/user/?client=".$client,
CURLOPT_RETURNTRANSFER =&gt; true,
CURLOPT_ENCODING =&gt; "",
CURLOPT_MAXREDIRS =&gt; 10,
CURLOPT_TIMEOUT =&gt; 30,
CURLOPT_HTTP_VERSION =&gt; CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST =&gt; "POST",
CURLOPT_POSTFIELDS =&gt; "",
CURLOPT_HTTPHEADER =&gt; array(
"authorization: ".$params."",
"content-type: application/json"
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

PHP Example with PATCH Method:

&lt;?php
$client				="client123";		//client id (provided by us)
$api_key 			= 'abcde123456';	//do not send this to the API endpoint (provided by us)

//encripted variables to be sent
$params['user']			="apitest";	//user id (given by your login system)
$params['subscription']		= 'ilimitada';
$params['email']   		= 'myemail@mydomain.com';
$params['first_name']		= 'apitest firstn';
$params['last_name']		= 'apitest lastn';
$params['company_name']	= 'apitest LLC';
$params['company_number']	= 'CNUM123456';
$params['phone']		= '123456789';
$params['address_street']	= 'apitest adress';
$params['address_city']		= 'apitest city';
$params['address_state']		= 'Madrid';
$params['address_postalcod']	= 'apitest postalc';
$params['address_country']	= 'apitest country';
$params['token']			=base64_encode(hash_hmac('sha512', $client.$user, $api_key, TRUE));
$params				=openssl_encrypt(json_encode( $params ),"AES-128-ECB",$api_key);

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL =&gt; "https://www.domibus.com/api/rest/v2/user/?client=".$client,
CURLOPT_RETURNTRANSFER =&gt; true,
CURLOPT_ENCODING =&gt; "",
CURLOPT_MAXREDIRS =&gt; 10,
CURLOPT_TIMEOUT =&gt; 30,
CURLOPT_HTTP_VERSION =&gt; CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST =&gt; "PATCH",
CURLOPT_POSTFIELDS =&gt; "",
CURLOPT_HTTPHEADER =&gt; array(
"authorization: ".$params."",
"content-type: application/json"
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

RESPONSES

Response Formats

All responses are 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.

Response Payload Changes

From time to time, we may add to the set of fields that is returned from a particular endpoint in the API. API clients should always be prepared to handle (i.e. ignore) any new object properties that they do not recognize.

HTTP Status Codes

Our REST API uses standard HTTP status codes to indicate success or failure of API 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.

Example1:

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

Example2:

{
"code": "property_param_province_missing",
"message": "Param (province) is missing",
"data": {
"status": 400,
"total": 0,
"list": ""
}
}

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. (Conditionally returned)
data Object This contains the the status object.
status Int The HTTP code.

Response Payload

Each API response is wrapped in a standard payload that contains the results of the API call, plus some additional useful information and metadata, such as the total count of records and the type of the result object.

Response - Property Listing

Name Type Description
code String Determines the code of the message.
message String An explanatory description about the response.
data Object This contains the actual results, i.e. the object or objects that you requested.
status Int The HTTP code.
total Int Total count of records that match your request. Because of pagination, this is not necessarily the number of records in the response.
items_per_page Int The max amount of items received per page inside list.
page Int The actual page you are in.
tpages Int The total amount of pages available with the given request.
list Object[] This contains a subset of results, i.e. the object or objects that you requested.

Here's an example of a response:

{
"code": "property_list",
"message": "List of properties",
"data": {
"status": 200,
"total": 3235,
"items_per_page": 2,
"page": 1,
"tpages": 1618,
"list": [
{
"id": "1033770",
"title": "Venta de  chalet en  València, San Antonio de Benagéber - Urb. SAN VICENTE",
"price": "220000.00",
"m2": "225",
"dorm": "3",
"wc": "0",
"provider": "idealista.com",
"date_indexed": "13-01-2017",
"date_updated": "03-05-2017",
"characteristics": "Chalet adosado^3 plantas^225 m² construidos^3 habitaciones^3 baños^Terraza^Plaza de garaje incluida en el precio^Segunda mano/buen estado^Armarios empotrados^Trastero^Aire acondicionado^Piscina^Jardín^Certificación energética: en trámite",
"description": "\"Vivienda unifamiliar en dos alturas más buhardilla, garaje para...",
"url": "",
"deleted": "0"
},
{
"id": "1090910",
"title": "Venta de  piso en  valencia, Museros",
"price": "129000.00",
"m2": "110",
"dorm": "3",
"wc": "2",
"provider": "habitaclia.com",
"date_indexed": "23-02-2017",
"date_updated": "03-05-2017",
"characteristics": "3 habitaciones^110 m²^Salón 27 m²^2 wc^Estado cocina: excelente^Trastero ^Calefacción^Plaza parking^Aire acondicionado^Planta número 3^Vistas al mar^Cerca de transporte público^Calificación energética :\nEn trámite^Ascensor",
"description": "Vivienda con reforma de diseño. A/A frío-calor por conductos en toda...",
"url": "",
"deleted": "0"
}
]
}
}

The above shows a successful response back from the call. In this case the result type is property, and there are two results. Note that the results are always an array even if you only requested one object.

Response - Access Data Source Information

Name Type Description
code String Determines the code of the message.
message String An explanatory description about the response.
data Object This contains the actual results, i.e. the object or objects that you requested.
status Int The HTTP code.
id Int The reference ID of a property.
url String The URL of the origin of the property.
acquisition_date String The date the property was acquired.

Here's an example of a response:

{
"code": "access_list",
"message": "Remote data access return",
"data": {
"status": 200,
"id": "941776",
"url": "https:\/\/www.idealista.com\/inmueble\/26304125\/",
"acquisition_date": "2017-05-11 22:34:39"
}
}

Response - Alert Management

Name Type Description
code String Determines the code of the message.
message String An explanatory description about the response.
data Object This contains the actual results, i.e. the object or objects that you requested.
status Int The HTTP code.
total int The number of results (alerts) gathered by de API
list Object[] This contains a subset of results, i.e. the object or objects that you requested.
id Int The reference ID of an alert.
title String The title given to that alert.
total int The number of properties found during the last 24 hours on this alert.

This will be shown when the alert is being processed

status int Determines de status of the current alert on Domibus 1=active, 0=inactive

Here's an example of a processed alert response:

{
"code": "alert_list",
"message": "List of alert results",
"data": {
"status": 200,
"total": 2,
"list": [
{
"id": 434,
"title": "Alerta de prueba - Madrid",
"total": 1,
"status": 1
},
{
"id": 435,
"title": "Test alerta2 - Madrid",
"total": 50,
"status": 1
}
]
}
}

Response – User Management

Name Type Description
code String Determines the code of the message.
message String An explanatory description about the response.
data Object This contains the actual results, i.e. the object or objects that you requested.
status Int The HTTP code.
list Object This contains a subset of results, i.e. the object or objects that you requested.
user String The current user ID.
subscription String The type of subscription.
email String The user email address.
first_name String The user First Name.
last_name String The user Last Name.
company_name String The name of the company of the user.
company_number String The company ID number (NIF/NIE).
phone String The company phone number.
address_street String The company street address.
address_city String The company City.
address_state String The company Stat/Province.
address_postalcod String The company ZIP Code.
address_country String The company Country (ES).

Here's an example of a GET response:

{
"code": "get_user_data",
"message": "Get user data",
"data": {
"status": 200,
"list": {
"user": "apitest",
"subscription": "Inactiva",
"email": "myemail@mydomain .com",
"first_name": "apitest firstn",
"last_name": "apitest lastn",
"company_name": "apitest LLC",
"company_number": "CNUM123489",
"phone": "123456789",
"address_street": "apitest adress",
"address_city": "apitest city",
"address_state": "Madrid",
"address_postalcod": "apitest postalc",
"address_country": "ES"
}
}
}

The above shows a successful response back from the call. In this case the result type is user.

Here's an example of a POST response:

{
"code": "user_created",
"message": "User created",
"data": {
"status": 200,
"list": {
"user": "apitest"
}
}
}

Here's an example of a PATCH response:

{
"code": "user_updated",
"message": "User updated.",
"data": {
"status": 200,
"list": {
"user": "apitest"
}
}
}

STRUCTURE/ENDPOINTS

The API structure can be found in https://www.domibus.com/api/