On this page

REALCUBE Documentation

If you want to integrate your app with REALCUBE, you have come to the right spot. REALCUBE has been developed with you in mind. Our product and development teams have made it easy for you to access real estate and technical asset data and to update the REALCUBE system with data g from your app.

We are in this together! The goal is to provide real estate owners, managers, and teams a central place to access real-time data which allows them to make critical decisions to increase their ROI.

The Business Basics

REALCUBE’s APIs let you access data related to real estate properties, buildings and units of buildings.

The APIs also provide access to the technical assets assigned to buildings, rooms, and floors.

You can also access data related to lease contracts with tenants and leasehold improvement contracts with landlords and owners.

The Technical Basics

Are you ready to get going? For starters, we recommend checking out our APIs by requesting a test account. We will generate an account just for you and automatically fill it with lots of data so you can explore all the API endpoints that we provide, without the pain of setting up test data.

When you request a test account, we will provide you with login credentials that you can use for easy and secure access to the APIs.

You can also access the APIs via Swagger UI, which offers a visual presentation of the REALCUBE endpoints.

SETUP

All REALCUBE APIs are described as Swagger documents.
This lets you generate API clients directly from the swagger.json files.
There is a large community available, providing client generators for almost every language.

For example, swagger code generator is a good project which allows generation of API clients for Ruby, Java, PHP, C#, NodeJS and more.
This will get you up to speed very fast, and as a bonus you can access API documentation within the auto-generated methods and models.

Integration with Third Party API Tools

We offer you ways to export all our endpoints to be tested by third party tools like Postman or Insomnia REST Client.
For this we have a specific endpoint

https://api.realcube.com/api/v1/docs.json

If we want to use let say postman, all we have to do is add the link and click import.

How to get started with the API

We need to generate an access token by using the POST /v1/users/log_in

Copied to Clipboard

curl -X POST ”http://api.realcube.com/api/v1/users/log_in" 
          -H "accept: application/json"
-H "content-type: application/json"
-d ‘{"email": "user@example.com", "password": "string"}’

The response will be:

Response body

{
    "user": {
    "id": 1,
    "api_key": "4113ec8b2dad2f09ee240daaa85daf953fac117d",
    "first_name": <your first name>,
    "last_name": <your last name>,
    "email": <your email>,
    "phone": <your phone>,
    "locale": "en",
    "created_at": "2019-01-30T08:50:36Z",
    "updated_at": "2020-04-03T13:16:29Z",
    "thumbnail_url": null,
    "images": []
  }
}

The value of the “api_key” attribute is your token.

The token/login endpoint will return the access token to pass in the header for all the calls to the API, like so:

The token/login endpoint will return the access token to pass in the header for all the calls to the API, like so:

X-Api-Key: <your token>

Or if you are using our Swagger UI, you click on the Authorize button on the top left, add the key on the panel, click Authorize and we are done, you can now authentify to use all the endpoints.

Asset integration guide

A facility is an asset, a technical equipment, usually specific to a building or unit. Common examples of facilities are elevators, heat systems, water pumps etc.

This guide explains how you can connect the assets managment application and keeping track of all your assets.

First, to create a new facility for a specific organization and building we need several parameters gathered from other endpoints responses, like:

1. facility_type_id, we can get the id of the facility type from the facility type endpoint:

GET /v1/facility_types

The response:

{
    "facility_type": {
    "id": 32,
    "code": "400",
    "group_1": null, "group_2": null, "group_3": null,
    "description": "All connected technical installations or plant components",
    "version": 1,
    "json_schema": {
    "type": "object",
        "required": [ "Beschreibung" ],
            "properties": {
                "Beschreibung": { "type": [ "string", "null" ],
                "title": "Description",
                "description": "Free text field General description of the object information)"
                }
            }
        }
    }
}

It returns the type of facilities that can be create on the API, also it returns something more interesting, the json_schema.
Sometimes we need to store different type of attributes on the database, but they are very dynamic and different and cannot be stored on the default fields.
Both schemas show the rules of the specific fields can be added for this specific type when general fields are not enough. We can specify the rules for this fields, the name, type, etc.
Both schemas apply the draft 4 version of json schema.
We need to select the id of the appropriate type and keep in mind the json_schema field.

2. type_dependent_attributes, we fill the json field with data that respect the rules specified at json_schema field above. For example, the schema of the response above dictates that we must provide field with the name ‘Beschreibung’ and we can add text like this: {“Beschreibung”: “example”}

3. manufacturer_id, we can get the id of the manufacturer from:

GET /v1/manufacturers

where we can search by name and get the id.

4. model_type_id, we also can specify the type of model for the related manufacturer at:

GET /v1/manufacturers/:manufacturer_id/model_types

5. location_type, specifies the location of the facility, if it is in a building, unit, property etc.

6. location_id, we can get the id by searching for our entity on endpoints:

GET /v1/buildings

GET /v1/properties

depending on the type

Working example

A working example is:

Copied to Clipboard

{
 "name": "facility1",
 "custom_id": "132465",
 "comment": "",
 "inventory_number": "1234",
 "serial_number": "S12345678",
 "year_of_construction": 1999,
 "last_inspection_at": "2020-03-17T14:20:19.261Z",
 "last_maintenance_at": "2020-03-17T14:20:19.261Z",
 "next_inspection_at": "2020-03-17T14:20:19.261Z",
 "next_maintenance_at": "2020-03-17T14:20:19.261Z",
 "latitude": 51.520599 ,
 "longitude": -0.147700,
 "type_dependent_attributes": { "Beschreibung": "Rechner Natalie" },
 "model_type_id": 1,
 "equipment_collection": true,
 "quantity": 10,
 "facility_parent": "",
 "facility_type_id": 163,
 "location_id": 178,
 "location_type": "building",
 "manufacturer_id": 8
}

And the response is:

{
"facility": {
    "id": 25,
    "name": "facility1",
    "custom_id": "custom",
    "comment": "test",
    "inventory_number": "1234",
    "serial_number": "string",
    "year_of_construction": 1999,
    "last_inspection_at": "2020-03-17T14:20:19Z",
    "last_maintenance_at": "2020-03-17T14:20:19Z",
    "next_inspection_at": "2020-03-17T14:20:19Z",
    "next_maintenance_at": "2020-03-17T14:20:19Z",
    "facility_parent": "string",
    "latitude": 0,
    "longitude": 0,
    "type_dependent_attributes": { "Beschreibung": "Rechner Natalie" },
    "quantity": 10,
    "equipment_collection": true,
    "manufacturer_type": "string",
    "user": { … },
    "last_editor": { … },
    "organisation": { … },
    "parent": null,
    "property": { … },
    "lot": null,
    "building": { … },
    "level": { … },
    "room": { … },
    "zone": { … },
    "manufacturer": { … },
    "facility_type": { … },
    "attachments": [],
    "images": [],
    "building_units": [],
    "activities": []
    }
}

Second endpoint of great importance is getting all the facilities inside an organization, based on several conditions. For this we have GET /v1/facilities where we can filter all facilities based on organisation, custom_id, inventory_number, serial_number, year_of_construction, the manufacturer, its department, facility_type, property, lot, building, level, room, zone, user.

A working request format would be:

Copied to Clipboard

curl -X GET api.realcube.com/api/v1/facilities?current_organisation_id=9
-H "accept: application/json"
-H "X-Api-Key: 5cff87653fa377152c901b518571065a819671f3

and the response would contain a list of the facilities with their manufacturer and facilities type.

{
    "facilities": [
        {
        "id": 6,
        "name": "Test Facility 1",
        "custom_id": "001",
        "comment": "This is a test facility",
        "inventory_number": "00001",
        "serial_number": "1",
        "year_of_construction": 2018,
        "last_inspection_at": "2018-01-05T09:30:38Z",
        "last_maintenance_at": "2018-01-05T09:30:38Z",
        "next_inspection_at": "2018-01-05T09:30:38Z",
        "next_maintenance_at": "2018-01-05T09:30:38Z",
        "facility_parent": null,
        "latitude": 48.1354181,
        "longitude": 11.6001928,
        "type_dependent_attributes": { "Beschreibung": "Beschreibung" },
        "quantity": null,
        "equipment_collection": null,
        "manufacturer_type": null,
        "user_id": 15,
        "created_at": "2018-01-05T11:42:48Z",
        "updated_at": "2018-01-05T11:42:48Z",
        "archived_at": null,
        "level": null,
        "room": null,
        "manufacturer": {
        "id": 1,
        "name": "Mitsubishi"
        },
            "facility_type": {
            "id": 4,
            "code": "332",
            "group_1": "BAUWERK - CONSTRUCTION CONSTRUCTIONS",
            "group_2": "Exterior walls, doors, gates and windows",
            "group_3": "Non-load-bearing outer walls",
            "description": "Columns and pillars with a cross-section ratio",
            "version": 1
            }
        }
    ]
}

Third, we can get a specific facility if with know the organization which it belongs to and its id.  The endpoint is GET /v1/facilities/{facility_id}, and the response would be the following:

Copied to Clipboard

{
    "facility": {
    "id": 25,
    "name": "facility1",
    "custom_id": "custom",
    "comment": "test",
    "inventory_number": "1234",
    "serial_number": "string",
    "year_of_construction": 1999,
    "last_inspection_at": "2020-03-17T14:20:19Z",
    "last_maintenance_at": "2020-03-17T14:20:19Z",
    "next_inspection_at": "2020-03-17T14:20:19Z",
    "next_maintenance_at": "2020-03-17T14:20:19Z",
    "facility_parent": "string",
    "latitude": 0,
    "longitude": 0,
    "type_dependent_attributes": {
    "Beschreibung": "Rechner Natalie"
    },
    "quantity": 10,
    "equipment_collection": true,
    "manufacturer_type": "string",
    "created_at": "2020-03-17T14:30:07Z",
    "updated_at": "2020-03-17T14:30:07Z",
    "thumbnail_url": null,
    "archived_at": null,
    "user": { … },
    "last_editor": { … },
    "organisation": { … },
    "parent": null,
    "property": { … },
    "lot": null,
    "building": {
    "building_type": { … },
    },
    "level": { … },
    "room": { … },
    
    "zone": null,
    "manufacturer": { … }
    "facility_type": { … },
    "attachments": [],
    "images": [],
    "building_units": [],
    "activities": []
    }
}

Forth, we may need to remove an existing facility which can be achieved by using the endpoint DELETE /v1/facilities/{facility_id}, if with know the organization which it belongs to and its id.

Copied to Clipboard

curl -X DELETE "api.realcube.com/api/v1/facilities/25?current_organisation_id=9"
-H "accept: application/json"
-H "X-Api-Key: 5cff87653fa377152c901b518571065a819671f3"

Or if we are an organization member we can also remove all its descendants within the current organisation by sending a request to:

DELETE /v1/facilities/{facility_id}/destroy_cascading

And its full request:

Copied to Clipboard

curl -X DELETE "api.realcube.com/api/v1/facilities/25/destroy_cascading?
current_organisation_id=9"
-H "accept: application/json"
-H "X-Api-Key: 5cff87653fa377152c901b518571065a819671f3"

I am text block. Click edit button to change this text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.