Manual Onboarding

Having a device (Entity) onboarded to our platform is required to start using many of our products and, therefore, a great starting point before exploring the other APIs.

Before connecting with energy devices through our platform, you must onboard them. We’ve developed Entity Onboarding Requests to help you collect the right information and consent necessary to connect with different types of energy devices.

​

What is an Entity Onboarding Request?

The purpose of an (Entity) Onboarding Request is to collect all the information necessary to identify the device or vehicle you are trying to connect with and to track the steps your user has to undertake to consent to the connection.

After a successful onboarding, the device or vehicle will be accessible as a connected Entity. We automatically create an Entity for each device or vehicle you connect with.

​

Types of Entities you can connect with

We offer connections to multiple types of devices — including EVs, solar inverters (PV), smart meters, and more. When you create an Onboarding Request, you need to specify the type of device that you want to onboard.

​

Overview of Entity Types & Manufacturers

Please note that this overview is just a snapshot. Access the full list of available Entity Types through theEntity Onboarding Types endpoint.

​

Creating an Onboarding Request

To create Onboarding Requests, we’re using the Post /onboarding/entities endpoint.

You can onboard any type of Entity (EVs, PV systems, Smart Meters, …) through an Entity Onboarding Request. However, the required parameters are specific to the type of Entity you’re connecting with.

​

Required Parameters

typerequired

Used to specify the type of Entity that you want to connect with.

manufacturerrequired

Used to specify the manufacturer (for example: “Audi” or “Huawei”) of the device or vehicle you want to connect with.

tenantIdrequired (defaults to the requester’s Tenant)

Entities always have to be linked with a Tenant (organisation). In case you’ve not specified a Tenant ID, we’ll attempt to determine the Tenant based on the user or client making the request. If we can’t, and no Tenant ID has been provided, the request will fail.

collectiveIdoptional

If set, the Entity will become part of the specified collective after it has been created.

Include an Identifying Attribute

In most cases, we’ll also require an identifying attribute that’s unique to the device or vehicle you’re connecting with. There are many different types of such attributes, but we’ve listed the most notable ones below.

vinoptionally required for Entities of type “EV”

Vehicle Identification Numbers are used to identify vehicles across all brands.

eanoptionally required for Entities of type “SmartMeter”

European Article Number are used to identify Smart Meters throughout Europe.

codeoptionally required for the re.alto P1-Dongle

A unique device-specific code, only accessible to the device owner.

Access the full list of available parameters through the API References.

​

Example Request

Onboarding an Audi vehicle only requires three parameters: type, manufacturer, and vin.

curl --request POST \
     --url https://platform.realto.io/api/v1/onboarding/entities \
     # Headers Omitted
     --data '
{
  "type": "EV",
  "manufacturer": "Audi",
  "vin": "WA1DMAFE0D0000000"
}
'

​

Example Response

{
    "id": "09bd2e8e-ba88-4216-[...]",
    "principalId": "441c436d-bd15-4a44-[...]",
    "requestType": "Entity",
    "data": {
        "entity": {
            "id": "9a16ff8e-c546-d772-[...]",
            "owner": "441c436d-bd15-4a44-[...]",
            "information": {
                "manufacturer": "Audi",
                "type": "EV",
                "vin": "WA1DMAFE0D0000000",
                "model": ""
            },
            "type": "EV",
        }
    },
    "status": "Pending",
    "transactions": [
        {
            "type": "CreateEntity",
            "status": "Pending"
        },
        {
            "type": "CreatePermissions",
            "status": "Pending"
        },
        {
            "type": "Connect",
            "status": "Pending"
        }
    ]
}