Common Integration

This section covers the data input layer shared by both the Engagement Service and the Intelligence Service. Regardless of which service you use, you need to authenticate, synchronize buildings, and send events.

Request Access Token

To perform operations with the MOOST API, it is essential to obtain a new access token. The steps to obtain and manage access tokens are as follows:

1. Request a New Token: Send a request to https://api.moost.io/auth/token/v1 with your client ID and client secret. The endpoint will issue a token that is valid for 86,400 seconds (24 hours).

2. Use the Token: Include the access token in the Authorization header of your API requests.

3. Token Expiration: Monitor the token's validity and request a new one before it expires to maintain uninterrupted access.

4. Refresh the Token: Once the token expires, repeat the process to lease a new access token.

Auth Token API

Receive a new access token

get

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

clientIdstringRequiredPattern: ^[a-zA-Z0-9]{1,100}$

clientSecretstringRequiredPattern: ^[a-zA-Z0-9_-]{1,100}$

Responses

200

Success. Valid access token obtained.

application/json

access_tokenstringRequiredPattern: ^[a-zA-Z0-9_]{1,100}$

expires_ininteger · int32Optional

scopestringOptional

token_typestring · enumRequiredPossible values:

401

Unauthorized. Client id or secret is invalid.

500

Server error. Failed to obtain a valid access token.

get

/auth/token/v1

HTTPcURLJavaScriptPython

GET /auth/token/v1?clientId=text&clientSecret=text HTTP/1.1
Host: api.moost.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "access_token": "text",
  "expires_in": 1,
  "scope": "text",
  "token_type": "Bearer"
}

Example with CURL

# use your own id and secret:
CLIENT_ID="6c............................Uo"
CLIENT_SECRET="Df.............................Ye"

curl -X GET "https://api.moost.io/auth/token/v1?clientId=$CLIENT_ID&clientSecret=$CLIENT_SECRET"

Sample response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 86400,
  "scope": "read:buildings write:buildings read:events write:events read:pushnotifications write:pushnotifications",
  "token_type": "Bearer"
}

You may store the access token in a variable for subsequent API calls:

ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIs..."

Then include it in all requests:

Authorization: Bearer $ACCESS_TOKEN

You find your clientId and clientSecret in the MOOST Admin Portal under Settings.

Synchronize Buildings and Devices

Make sure all buildings which shall be taken into consideration by the MOOST Platform are synchronised to MOOST. New buildings shall be created, and changed building states shall be updated (including deactivation and reactivation) via MOOST API.

Building Data Structure

Following example depicts a building located in Dresden, with connected devices and dual tariff:

{
  "id": "66d07a7fd51e3528aa5673ba",
  "customerId": "656730be2bc9719e6e5ed51d",
  "customerBuildingId": "99900000C048ADA6",
  "zip": "01067",
  "city": "Dresden",
  "countryCode": "DE",
  "timeZoneId": "Europe/Berlin",
  "geolocation": {
    "lat": 47.2383918762207,
    "lon": 8.284913063049316
  },
  "registrationTimestamp": 1645630735,
  "activationTimestamp": 1645640000,
  "isEarlyAdopter": false,
  "userIds": ["user2547865"],
  "disabledNotifications": [
    {
      "ruleId": "63fb7ac54978916150dc5572",
      "userId": "user2547865"
    }
  ],
  "inactiveRules": [],
  "devices": [
    {
      "id": "656830efc4515778b1ce4f2f",
      "type": "CAR",
      "name": "John's Car",
      "product_name": "Device Link Car",
      "createdAt": 1701327087,
      "updatedAt": 1724896211
    },
    {
      "id": "621660e410c1012648d7bed2",
      "type": "CAR_CHARGER",
      "name": "easee Home",
      "product_name": "easee Home",
      "createdAt": 1645633761,
      "updatedAt": 1724936865
    }
  ],
  "settings": {
    "tariff": {
      "type": "DUAL",
      "minPrice": "0.296",
      "maxPrice": "0.385",
      "currency": "EUR",
      "dual": {
        "lowTariff": {
          "mondayStartTime": "19:00",
          "mondayEndTime": "07:00",
          "tuesdayStartTime": "19:00",
          "tuesdayEndTime": "07:00",
          "wednesdayStartTime": "19:00",
          "wednesdayEndTime": "07:00",
          "thursdayStartTime": "19:00",
          "thursdayEndTime": "07:00",
          "fridayStartTime": "19:00",
          "fridayEndTime": "07:00",
          "saturdayStartTime": "00:00",
          "saturdayEndTime": "07:00",
          "sundayStartTime": "00:00",
          "sundayEndTime": "07:00"
        }
      }
    }
  },
  "properties": {}
}

Data Structure Attributes

Attribute	Description
id	The building ID on MOOST side (generated when inserting a new building).
customerId	The ID of the customer (cannot be set or changed).
customerBuildingId	The building ID on customer side.
zip	Postal code.
city	Name of the city.
countryCode	Country code (ISO 3166-1 alpha-2).
timeZoneId	The IANA time zone of the building. Automatically added by MOOST if not provided (and verified if provided).
geolocation	The geo location of the building (ISO 6709). Automatically added by MOOST if not provided.
registrationTimestamp	Epoch time (seconds, UTC) when the building was registered on customer side.
activationTimestamp	Epoch time (seconds, UTC) when the building was added to MOOST. Automatically set by MOOST when inserting a new building.
deactivatedTimestamp	If building has been deregistered and shall no longer receive notifications, this attribute is set (Epoch time in seconds, UTC).
isEarlyAdopter	If true, the building also receives notifications from rules marked for "Early Adopter" (typically new rules tested on a small user base).
devices	List of devices. Each device contains id, type (see Device Types), and product_name.
userIds	A list of users attached to the building. If present, push notifications can be disabled for individual users instead of for the entire building.
disabledNotifications	If userIds are attached, this may contain a list of disabled rules per user.
inactiveRules	A list of disabled rules for this building.
settings.tariff	Tariff data for the building. See Tariff Configuration below.

When reading building data, there might be additional attributes such as profile or geolocation. These fields are calculated by MOOST and should not be modified by the customer.

Tariff Configuration

Buildings support three tariff models, configured in settings.tariff:

Single tariff — flat rate, no additional configuration needed:

{
  "settings": {
    "tariff": {
      "type": "SINGLE",
      "minPrice": "34.95",
      "maxPrice": "34.95",
      "currency": "CHF"
    }
  }
}

Dual tariff — defines the low-tariff time window for each day of the week:

{
  "settings": {
    "tariff": {
      "type": "DUAL",
      "minPrice": "0.296",
      "maxPrice": "0.385",
      "currency": "EUR",
      "dual": {
        "lowTariff": {
          "mondayStartTime": "19:00",
          "mondayEndTime": "07:00"
        }
      }
    }
  }
}

Dynamic tariff — defines time slices with individual prices (typically for 1–2 days ahead):

{
  "settings": {
    "tariff": {
      "type": "DYNAMIC",
      "minPrice": "0.1231",
      "maxPrice": "0.3334",
      "currency": "EUR",
      "dynamic": {
        "tariffs": [
          { "price": "0.1546", "from": 1732212000, "to": 1732212900 },
          { "price": "0.1546", "from": 1732212900, "to": 1732213800 }
        ]
      }
    }
  }
}

{% hint style="info" %} The currency, minPrice, and maxPrice attributes are optional and are per-kWh based. If dual or dynamic tariff settings are defined, MOOST is able to generate additional tariff-related events. {% endhint %}

Building API Endpoints

Method	Endpoint	Description
POST	/buildings/v1	Create a building. Returns 201 on success, 409 if building already exists.
PUT	/buildings/v1	Update a building. Returns 200 on success, 404 if not found.
GET	/buildings/v1?activeOnly=false	Get all buildings.
GET	/buildings/core-data/v1?activeOnly=false	Get core data of all buildings (lightweight — without devices, settings, profile).
GET	/buildings/{customerBuildingId}/v1	Get a single building.
DELETE	/buildings/{customerBuildingId}/v1	Delete a building.
PUT	/buildings/{customerBuildingId}/devices/v1	Attach a set of devices to a building.

When a building is created in EXCLUDE mode and no activeRules are provided, all existing rules of the customer are automatically added to the building.

Device Types

The household itself is referred to as GATEWAY. Every event received with device type GATEWAY represents a value for the total of the household. The following device types are supported:

Device Type	Description
GATEWAY	The household itself. Used for whole-building measurements.
SMART_METER	A smart meter used to monitor energy passing through.
INVERTER	A power inverter (DC to AC).
BATTERY	A battery used to store energy.
CAR	A car connected to the HEMS.
CAR_CHARGER	A car charger in the household.
HEAT_PUMP	A heat pump connected to the system.
SMART_PLUG	A smart plug to control a connected device.
SOLAR_PANEL	A solar panel connected to the system.
WATER_HEATER	A water heater connected to the system.
THERMOSTAT	A thermostat to measure temperature.
SWITCH	A smart switch (e.g. for lights).
ENERGY_MEASUREMENT	A device solely used to measure energy.
APPLIANCE	Any appliance that does not fit into another category.
WALL_TABLET	A wall tablet used to control the HEMS.
THERMAL_ZONE / THERMAL_STORAGE	Thermal zone or storage components.
DISHWASHER / DRYER / WASHING_MACHINE / OVEN / REFRIGERATION / LIGHTING / ENTERTAINMENT	Specific household appliances.

Add Events

Make sure that event data which shall be taken into consideration by the MOOST Platform are forwarded to MOOST via MOOST API. See Event Types below for an overview of which events should be forwarded for which devices and at which interval.

Event Data Structure

Following example depicts an energy consumption event:

{
  "customerId": "656730be2bc9719e6e5ed51d",
  "customerBuildingId": "99900000C048ADA6",
  "deviceId": "c8f09e83046c",
  "deviceName": "Sinemaa main meter",
  "source": "GATEWAY",
  "type": "ENERGY_CONSUMPTION",
  "value": 858.71,
  "timestamp": 1727992800
}

Data Structure Attributes

Attribute	Description
id	The event ID on MOOST side (generated when inserting a new event).
customerId	The ID of the customer (cannot be set or changed).
customerBuildingId	The building ID on customer side.
deviceId	The ID of the device producing this event (should refer to the device within the building).
deviceName	The name of the device. If the device does not have its own name, the product name can be used.
source	The device type related to this event (see Device Types). Use GATEWAY when this is a data point for the whole household/building.
type	The event type. This value also implies the data unit. See Event Types.
value	The value of the event data point. Must be a number.
timestamp	Time of the event (Epoch time in seconds, UTC).

Add an Event

Add an event to a building

post

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

timestampinteger · int64Optional

customerIdstringRequiredPattern: ^[a-zA-Z0-9]{24}$

customerBuildingIdstringRequiredPattern: ^[a-zA-Z0-9:._-]{1,100}$

deviceIdstringRequiredPattern: ^[a-zA-Z0-9:._-]{3,64}$

deviceNamestringRequiredPattern: ^.{1,100}$

valuenumber · floatRequired

typestring · enumRequiredPossible values:

sourcestring · enumOptionalPossible values:

forecastTimestampinteger · int64Optional

ingestionTimestampinteger · int64Optional

Responses

201

Success. Event accepted.

400

Invalid event data, e.g. because specified customerBuildingId is unknown.

post

/events/v1

HTTPcURLJavaScriptPython

POST /events/v1 HTTP/1.1
Host: api.moost.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 200

{
  "timestamp": 1,
  "customerId": "text",
  "customerBuildingId": "text",
  "deviceId": "text",
  "deviceName": "text",
  "value": 1,
  "type": "CHARGING_MODE",
  "source": "APPLIANCE",
  "forecastTimestamp": 1,
  "ingestionTimestamp": 1
}

No content

Example with CURL:

curl -X POST "https://api.moost.io/events/v1" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "656730be2bc9719e6e5ed51d",
    "customerBuildingId": "99900000C048ADA6",
    "deviceId": "c8f09e83046c",
    "deviceName": "Sinemaa main meter",
    "source": "GATEWAY",
    "type": "ENERGY_CONSUMPTION",
    "value": 858.71,
    "timestamp": 1727992800
  }'

Insert Historical Events

Inserts historical events to the database. I.e. these events are not processed by the rule engine when receiving these events.Event customerId has to be in-line with customerId of the JWT).

post

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Bodyobject[]

application/json

timestampinteger · int64Optional

customerIdstringRequiredPattern: ^[a-zA-Z0-9]{24}$

customerBuildingIdstringRequiredPattern: ^[a-zA-Z0-9:._-]{1,100}$

deviceIdstringRequiredPattern: ^[a-zA-Z0-9:._-]{3,64}$

deviceNamestringRequiredPattern: ^.{1,100}$

valuenumber · floatRequired

typestring · enumRequiredPossible values:

sourcestring · enumOptionalPossible values:

forecastTimestampinteger · int64Optional

ingestionTimestampinteger · int64Optional

Responses

200

Success. All events have been inserted.

No content

400

Invalid event data.

*/*

500

Internal error. None or only part of the data could be written.

post

/events/historical/v1

HTTPcURLJavaScriptPython

POST /events/historical/v1 HTTP/1.1
Host: api.moost.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 202

[
  {
    "timestamp": 1,
    "customerId": "text",
    "customerBuildingId": "text",
    "deviceId": "text",
    "deviceName": "text",
    "value": 1,
    "type": "CHARGING_MODE",
    "source": "APPLIANCE",
    "forecastTimestamp": 1,
    "ingestionTimestamp": 1
  }
]

No content

Accepts an array of event objects. Historical events are stored in the database but not processed by the rule engine. Use this endpoint for backfilling data.

Event Types

Every event that occurs on a sensor or actor within a building can be seen as a change of a state. Below you find the event types the platform can receive from your environment.

MOOST recommends sending an update for each sensor every 15 minutes. Avoid excessive event generation to prevent unnecessary processing and network overhead.

Customer Provided Types

Event Type	Unit	Interval	Device Type	Description
ENERGY_CONSUMPTION	Wh	Every 15 min	ALL	Energy consumption of the last time interval.
ENERGY_CONSUMPTION_YESTERDAY	Wh	Once a day	ALL	Energy consumed on the previous calendar day.
ENERGY_GENERATION	Wh	Every 15 min	GATEWAY	Energy generation of the last time interval.
ENERGY_GENERATION_YESTERDAY	Wh	Once a day	GATEWAY	Energy generated on the previous calendar day.
GRID_ENERGY_CONSUMPTION	Wh	Every 15 min	GATEWAY	Energy consumption from the grid of the last time interval.
GRID_ENERGY_CONSUMPTION_YESTERDAY	Wh	Once a day	GATEWAY	Energy consumption from the grid on the previous day.
POWER_CONSUMPTION	W	Every 15 min	ALL	Current power consumed.
POWER_GENERATION	W	Every 15 min	GATEWAY	Current power generated.
POWER_EXCESS	W	Every 15 min	GATEWAY	Current power excess.
GRID_POWER_CONSUMPTION	W	Every 15 min	GATEWAY	Current power consumed from the grid.
ENERGY_IMPORT	Wh	Every 15 min	BATTERY	Energy used to charge a battery.
ENERGY_IMPORT_YESTERDAY	Wh	Once a day	BATTERY	Energy used to charge a battery on the previous day.
ENERGY_EXPORT	Wh	Every 15 min	BATTERY	Energy drawn from a battery.
ENERGY_EXPORT_YESTERDAY	Wh	Once a day	BATTERY	Energy drawn from a battery on the previous day.
ENERGY_EXCESS	Wh	Every 30 min	GATEWAY	Energy excess of the last time interval.
ENERGY_EXCESS_YESTERDAY	Wh	Once a day	GATEWAY	Energy excess on the previous calendar day.
SELF_CONSUMPTION_RATE	%	Every 15 min	GATEWAY	Current self-consumption rate.
SELF_CONSUMPTION_RATE_YESTERDAY	%	Once a day	GATEWAY	Self-consumption rate on the previous day.
SELF_SUFFICIENCY_RATE	%	Every 15 min	GATEWAY	Current self-sufficiency rate.
SELF_SUFFICIENCY_RATE_YESTERDAY	%	Once a day	GATEWAY	Self-sufficiency rate on the previous day.
STATE_OF_CHARGE_RATE	%	On change	CAR	Current state of charge as percentage.
CHARGING_MODE	ID [0..7]	On change	CAR_CHARGER, HEAT_PUMP, BATTERY, SMART_PLUG	Current charging mode of a device.
DEVICE_STATUS	ID [-1..4]	On change	ALL	State of a device.
SWITCH_STATE	ID	On change	SMART_PLUG, CAR_CHARGER, SWITCH	Connection state of a switch.
TEMPERATURE	°C	Every 15 min	THERMOSTAT	Current temperature.
WATER_TEMPERATURE	°C	Every 15 min	HEAT_PUMP, WATER_HEATER	Current water temperature.

MOOST Provided Types (Context Services)

These event types are generated by MOOST context services and do not need to be provided by you.

Event Type	Unit	Interval	Description
EXPECTED_OUTSIDE_TEMPERATURE	°C	Once a day	Expected outside temperature for the next calendar day.
EXPECTED_OUTSIDE_TEMPERATURE_4DAYS	°C	Once a day	Expected outside temperature in 4 days.
POWER_GENERATION_FORECAST_1H	W	Every hour	Expected power generated in the next hour.
POWER_GENERATION_FORECAST_24H	W	Every hour	Expected power generated in the next 24 hours.
POWER_GENERATION_FORECAST_TOMORROW	W	Once a day	Expected power generated on the next calendar day.
POWER_CONSUMPTION_FORECAST_1H	W	Every hour	Expected power consumption in one hour.
POWER_CONSUMPTION_FORECAST_24H	W	Every hour	Expected power consumption in 24 hours.
ENERGY_BASE_CONSUMPTION	Wh	Once a day	Calculated base consumption from recent data.
GRID_ENERGY_BASE_CONSUMPTION	Wh	Once a day	Calculated grid base consumption.
DYNAMIC_TARIFF_PRICE	currency	Every 30 min	Current tariff price for dynamic tariff buildings.
DYNAMIC_TARIFF_PRICE_FORECAST_1H	currency	Every 30 min	Tariff price of next hour.
ENERGY_CONSUMPTION_FORECAST_1H	Wh	Every hour	Expected energy consumption in the next hour.
ENERGY_GENERATION_FORECAST_1H	Wh	Every hour	Expected energy generation in the next hour.

Context services such as Weather Forecast, Solar Production Forecast, and Power Consumption Forecast are automatically enabled for customers who provide a ZIP code and geolocation for their buildings. The Power Consumption Forecast and Power Generation Forecast are available in the Premium subscription.