Version 2.5
June , 2022
Table of Contents
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 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, token, email and hash are always mandatory). 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.
The authentication happens in every call against our API by adding both the variable client and params.
PHP Example:
$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?client=clientid
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&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. |
user The identifier of the user from the client company (Mandatory) | ||
token Is a hash provided by the authentication script (Mandatory) | ||
hash It is a unique user identifier to facilitate integration and communication between platforms (Mandatory) | ||
first_name (Mandatory when billing through Domibus platform) | ||
last_name (Mandatory when billing through Domibus platform) | ||
email (Mandatory) | ||
company_name (Mandatory when billing through Domibus platform) | ||
company_number (Mandatory when billing through Domibus platform) | ||
phone (Mandatory when billing through Domibus platform) | ||
address_street (Optional when using the methods POST/PATCH) | ||
address_city (Mandatory when billing through Domibus platform) | ||
address_state (Mandatory when billing through Domibus platform) | ||
address_postalcod (Mandatory when billing through Domibus platform) | ||
address_country (Mandatory when billing through Domibus platform) | ||
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')
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=”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', '3mes'=>'El últimos 3 meses') |
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.
Example
$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 = "https://www.domibus.com/api/rest/v2/property/1000331?client=".$client, CURLOPT_RETURNTRANSFER = true, CURLOPT_ENCODING = "", CURLOPT_MAXREDIRS = 10, CURLOPT_TIMEOUT = 30, CURLOPT_HTTP_VERSION = CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST = "GET", CURLOPT_POSTFIELDS = "", CURLOPT_HTTPHEADER = 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?client=clientid
Available Parameters
Parameter | Value | Description |
id | Int | The reference ID of a property. (Mandatory) |
params | String | JSON encoded variables that will be OpenSSL encrypted and passed as a hashed string. |
user The identifier of the user from the client company (Mandatory) | ||
token Is a hash provided by the authentication script (Mandatory) | ||
hash It is a unique user identifier to facilitate integration and communication between platforms (Mandatory) | ||
first_name (Mandatory when billing through Domibus platform) | ||
last_name (Mandatory when billing through Domibus platform) | ||
email (Mandatory) | ||
company_name (Mandatory when billing through Domibus platform) | ||
company_number (Mandatory when billing through Domibus platform) | ||
phone (Mandatory when billing through Domibus platform) | ||
address_street (Optional when using the methods POST/PATCH) | ||
address_city (Mandatory when billing through Domibus platform) | ||
address_state (Mandatory when billing through Domibus platform) | ||
address_postalcod (Mandatory when billing through Domibus platform) | ||
address_country (Mandatory when billing through Domibus platform) |
Examples
$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 = "https://www.domibus.com/api/rest/v2/access/900234?client=".$client, CURLOPT_RETURNTRANSFER = true, CURLOPT_ENCODING = "", CURLOPT_MAXREDIRS = 10, CURLOPT_TIMEOUT = 30, CURLOPT_HTTP_VERSION = CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST = "GET", CURLOPT_POSTFIELDS = "", CURLOPT_COOKIE = "wfvt_1492410860=591977b3ed37a", CURLOPT_HTTPHEADER = 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?client=clientid
GET alert by user:
/rest/v2/alert
https://www.domibus.com/api/rest/v2/alert?client=clientid
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'”. |
params | String | JSON encoded variables that will be OpenSSL encrypted and passed as a hashed string. |
user The identifier of the user from the client company (Mandatory) | ||
token Is a hash provided by the authentication script (Mandatory) | ||
hash It is a unique user identifier to facilitate integration and communication between platforms (Mandatory) | ||
first_name (Mandatory when billing through Domibus platform) | ||
last_name (Mandatory when billing through Domibus platform) | ||
email (Mandatory) | ||
company_name (Mandatory when billing through Domibus platform) | ||
company_number (Mandatory when billing through Domibus platform) | ||
phone (Mandatory when billing through Domibus platform) | ||
address_street (Optional when using the methods POST/PATCH) | ||
address_city (Mandatory when billing through Domibus platform) | ||
address_state (Mandatory when billing through Domibus platform) | ||
address_postalcod (Mandatory when billing through Domibus platform) | ||
address_country (Mandatory when billing through Domibus platform) |
Examples
PHP Example with no action specified:
$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 = "https://www.domibus.com/api/rest/v2/alert/900234?client=".$client, CURLOPT_RETURNTRANSFER = true, CURLOPT_ENCODING = "", CURLOPT_MAXREDIRS = 10, CURLOPT_TIMEOUT = 30, CURLOPT_HTTP_VERSION = CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST = "GET", CURLOPT_POSTFIELDS = "", CURLOPT_COOKIE = "wfvt_1492410860=591977b3ed37a", CURLOPT_HTTPHEADER = 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:”
$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 = "https://www.domibus.com/api/rest/v2/alert/900234?client=".$client."action=process", CURLOPT_RETURNTRANSFER = true, CURLOPT_ENCODING = "", CURLOPT_MAXREDIRS = 10, CURLOPT_TIMEOUT = 30, CURLOPT_HTTP_VERSION = CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST = "GET", CURLOPT_POSTFIELDS = "", CURLOPT_COOKIE = "wfvt_1492410860=591977b3ed37a", CURLOPT_HTTPHEADER = 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?client=clientid
POST (create) user:
/rest/v2/user/
https://www.domibus.com/api/rest/v2/user?client=clientid
PATCH (update) current user:
/rest/v2/user/
https://www.domibus.com/api/rest/v2/user?client=clientid
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. |
user The identifier of the user from the client company (Mandatory) | ||
token Is a hash provided by the authentication script (Mandatory) | ||
hash It is a unique user identifier to facilitate integration and communication between platforms (Mandatory) | ||
first_name (Mandatory when billing through Domibus platform) | ||
last_name (Mandatory when billing through Domibus platform) | ||
subscription (Mandatory when using the methods POST/PATCH)
Values: ('demo'=>'demo', 'ilimitata'=>'ilimitata') |
||
email (Mandatory) | ||
company_name (Mandatory when billing through Domibus platform) | ||
company_number (Mandatory when billing through Domibus platform) | ||
phone (Mandatory when billing through Domibus platform) | ||
address_street (Optional when using the methods POST/PATCH) | ||
address_city (Mandatory when billing through Domibus platform) | ||
address_state (Mandatory when billing through Domibus platform) | ||
address_postalcod (Mandatory when billing through Domibus platform) | ||
address_country (Mandatory when billing through Domibus platform) | ||
agreement (Optional when using the methods POST/PATCH)
Values: ('0'=>'0', '1'=>'1') |
Examples
PHP Example with GET Method:
$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 = "https://www.domibus.com/api/rest/v2/user/?client=".$client, CURLOPT_RETURNTRANSFER = true, CURLOPT_ENCODING = "", CURLOPT_MAXREDIRS = 10, CURLOPT_TIMEOUT = 30, CURLOPT_HTTP_VERSION = CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST = "GET", CURLOPT_POSTFIELDS = "", CURLOPT_HTTPHEADER = 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:
$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 = "https://www.domibus.com/api/rest/v2/user/?client=".$client, CURLOPT_RETURNTRANSFER = true, CURLOPT_ENCODING = "", CURLOPT_MAXREDIRS = 10, CURLOPT_TIMEOUT = 30, CURLOPT_HTTP_VERSION = CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST = "POST", CURLOPT_POSTFIELDS = "", CURLOPT_HTTPHEADER = 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:
$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 = "https://www.domibus.com/api/rest/v2/user/?client=".$client, CURLOPT_RETURNTRANSFER = true, CURLOPT_ENCODING = "", CURLOPT_MAXREDIRS = 10, CURLOPT_TIMEOUT = 30, CURLOPT_HTTP_VERSION = CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST = "PATCH", CURLOPT_POSTFIELDS = "", CURLOPT_HTTPHEADER = 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. | ||||
login_url | String | The current user ID. | ||||
user | String | The current user ID. | ||||
subscription | String | The type of subscription. | ||||
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/