Hiven API

Download OpenAPI specification:Download

REST API dedicated for Hiven's partners

User location API

updateUserLocation

Update a location of a user

Authorizations:

apiKey

path Parameters

userId required	string
id required	string

Request Body schema: application/json

name	string
	object (Coordinates)
countryCode	string ISO 3166-1 alpha-2 country code
postalCode	string Postal code
streetAddress	string Street address
city	string City
	object (TariffInfo) Tariff information

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"coordinates": {"latitude": 59.23655,
"longitude": 18.09419
},
"countryCode": "SE",
"postalCode": "11130",
"streetAddress": "Slottsbacken 1",
"city": "Stockholm",
"tariffInfo": {"electricalUtilityProvider": "string",
"meterId": "string",
"tariff": "string"
}
}

deleteUserLocation

Delete a location of a user

Authorizations:

apiKey

path Parameters

userId required	string
id required	string

Responses

updateUserLocationTariffInfo

Updates tariff information in specified location

Authorizations:

apiKey

path Parameters

userId required	string
id required	string

Request Body schema: application/json

electricalUtilityProvider	string
meterId	string
tariff	string

Responses

Request samples

Payload

Content type

application/json

{"electricalUtilityProvider": "string",
"meterId": "string",
"tariff": "string"
}

deleteUserLocationTariffInfo

Deletes tariff info from specified location

Authorizations:

apiKey

path Parameters

userId required	string
id required	string

Responses

getUserLocations

Get user's locations

Authorizations:

apiKey

path Parameters

userId

required

string

Responses

addUserLocation

Add a new location for a user

Authorizations:

apiKey

path Parameters

userId

required

string

Request Body schema: application/json

name	string
	object (Coordinates)
countryCode	string ISO 3166-1 alpha-2 country code
postalCode	string Postal code
streetAddress	string Street address
city	string City
	object (TariffInfo) Tariff information

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"coordinates": {"latitude": 59.23655,
"longitude": 18.09419
},
"countryCode": "SE",
"postalCode": "11130",
"streetAddress": "Slottsbacken 1",
"city": "Stockholm",
"tariffInfo": {"electricalUtilityProvider": "string",
"meterId": "string",
"tariff": "string"
}
}

Users API

getUserData

Authorizations:

apiKey

path Parameters

userId

required

string

Responses

saveUserData

Authorizations:

apiKey

path Parameters

userId

required

string

Request Body schema: application/json

electricalUtilityProvider	string
meterId	string
tariff	string

Responses

Request samples

Payload

Content type

application/json

{"electricalUtilityProvider": "string",
"meterId": "string",
"tariff": "string"
}

deleteUserData

Authorizations:

apiKey

path Parameters

userId

required

string

Responses

signOut

Authorizations:

apiKey

path Parameters

userId

required

string

Responses

Devices API

getOCPPChargerPreferences

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200

Content type

application/json

{"chargingBehavior": "SMART_CHARGE_OFF",
"readyTime": "07:00",
"weekDaySpecificReadyTimes": {"MONDAY": "08:00"
},
"targetSoC": {"value": 0,
"unit": "PERCENT"
},
"locationId": "string",
"minimalSoC": {"value": 0,
"unit": "PERCENT"
},
"batteryCapacity": 0,
"efficiency": 0,
"currentSoC": {"value": 0,
"unit": "PERCENT"
},
"associatedDeviceId": "string",
"minimumEnergyTransfer": {"value": 0,
"unit": "kWh"
},
"targetEnergyTransfer": {"value": 0,
"unit": "kWh"
}
}

putOCPPChargerPreferences

Authorizations:

apiKey

path Parameters

deviceId

required

string

Request Body schema: application/json

chargingBehavior	string Enum: "SMART_CHARGE_OFF" "SMART_CHARGE_ON"
readyTime	string
	object
	object (BatterySoCEntry)
locationId	string Id of the location where the charger is located
	object (BatterySoCEntry)
batteryCapacity	number <double>
efficiency	number <double>
	object (BatterySoCEntry)
associatedDeviceId	string
	object (EnergyTransferEntry)
	object (EnergyTransferEntry)

Responses

Request samples

Payload

Content type

application/json

{"chargingBehavior": "SMART_CHARGE_OFF",
"readyTime": "07:00",
"weekDaySpecificReadyTimes": {"MONDAY": "08:00"
},
"targetSoC": {"value": 0,
"unit": "PERCENT"
},
"locationId": "string",
"minimalSoC": {"value": 0,
"unit": "PERCENT"
},
"batteryCapacity": 0,
"efficiency": 0,
"currentSoC": {"value": 0,
"unit": "PERCENT"
},
"associatedDeviceId": "string",
"minimumEnergyTransfer": {"value": 0,
"unit": "kWh"
},
"targetEnergyTransfer": {"value": 0,
"unit": "kWh"
}
}

getEvPreferences

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200

Content type

application/json

{"chargingBehavior": "SMART_CHARGE_OFF",
"previousChargingBehavior": "SMART_CHARGE_OFF",
"chargingLocationIds": ["string"
],
"chargingLocations": [{"locationId": "string",
"coordinates": {"latitude": 59.23655,
"longitude": 18.09419
},
"countryCode": "SE",
"postalCode": "12346",
"spotPriceAreaId": "SE3",
"id": "string"
}
],
"defaultSpotPriceAreaId": "SE3",
"readyTime": "07:00",
"weekDaySpecificReadyTimes": {"MONDAY": "08:00"
},
"targetSoC": {"value": 0,
"unit": "PERCENT"
},
"minimalSoC": {"value": 0,
"unit": "PERCENT"
},
"batteryCapacity": 0
}

updateEvPreferences

Authorizations:

apiKey

path Parameters

deviceId

required

string

Request Body schema: application/json

chargingBehavior	string Enum: "SMART_CHARGE_OFF" "SMART_CHARGE_AT_LOCATION" "SMART_CHARGE_ANYWHERE"
chargingLocationIds	Array of strings
	Array of objects (ChargingLocation) Deprecated to be removed, use `chargingLocationsIds` instead
defaultSpotPriceAreaId	string
readyTime	string
	object
	object (BatterySoCEntry)
	object (BatterySoCEntry)
batteryCapacity	number <double>

Responses

Request samples

Payload

Content type

application/json

{"chargingBehavior": "SMART_CHARGE_OFF",
"chargingLocationIds": ["string"
],
"chargingLocations": [{"locationId": "string",
"coordinates": {"latitude": 59.23655,
"longitude": 18.09419
},
"countryCode": "SE",
"postalCode": "12346",
"spotPriceAreaId": "SE3",
"id": "string"
}
],
"defaultSpotPriceAreaId": "SE3",
"readyTime": "07:00",
"weekDaySpecificReadyTimes": {"MONDAY": "08:00"
},
"targetSoC": {"value": 0,
"unit": "PERCENT"
},
"minimalSoC": {"value": 0,
"unit": "PERCENT"
},
"batteryCapacity": 0
}

registerCharger

Authorizations:

apiKey

header Parameters

X-User-Id

required

string

Request Body schema: application/json

name	string
vendor	string Value: "WALLBOX"
vendorDeviceId	string
autoSetupOCPPConnection	boolean

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"vendor": "WALLBOX",
"vendorDeviceId": "string",
"autoSetupOCPPConnection": true
}

getHeatingPreferences

get smart heating device preferences

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200
400
404

Content type

application/json

{"minComfortLimit": 19.5,
"maxComfortLimit": 20.5,
"heatingSchedule": {"timeZoneId": "Europe/Stockholm",
"entries": [{"dayOfWeek": "MONDAY",
"time": "string",
"minComfortTemp": 19.5,
"maxComfortTemp": 20.5,
"id": "string"
}
]
},
"heatingBehavior": "SMART_HEATING_ON",
"location": {"countryCode": "SE",
"postalCode": "12346"
},
"spotPriceAreaId": "SE3"
}

patchHeatingPreferences

update smart heating device preferences

Authorizations:

apiKey

path Parameters

deviceId

required

string

Request Body schema: application/json

heating preferences with temperatures expressed in degrees Celsius

minComfortLimit	number minimum comfort limit temperature in degrees Celsius
maxComfortLimit	number maximum comfort limit temperature in degrees Celsius
	object (HeatingSchedule)
heatingBehavior	string Enum: "SMART_HEATING_ON" "SMART_HEATING_OFF"
	object (HeaterLocation)

Responses

Request samples

Payload

Content type

application/json

{"minComfortLimit": 19.5,
"maxComfortLimit": 20.5,
"heatingSchedule": {"timeZoneId": "Europe/Stockholm",
"entries": [{"dayOfWeek": "MONDAY",
"time": "string",
"minComfortTemp": 19.5,
"maxComfortTemp": 20.5,
"id": "string"
}
]
},
"heatingBehavior": "SMART_HEATING_ON",
"location": {"countryCode": "SE",
"postalCode": "12346"
}
}

getUserDevices

Authorizations:

apiKey

query Parameters

userId

required

string

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"type": "VEHICLE",
"integration": "SMARTCAR",
"createdAt": "2019-08-24T14:15:22Z",
"attributes": {"property1": { },
"property2": { }
},
"settings": {"property1": { },
"property2": { }
},
"associatedToCharger": true,
"associatedChargerIds": ["string"
]
}
]

getDeviceById

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200

Content type

application/json

{"id": "string",
"type": "VEHICLE",
"integration": "SMARTCAR",
"createdAt": "2019-08-24T14:15:22Z",
"attributes": {"property1": { },
"property2": { }
},
"settings": {"property1": { },
"property2": { }
},
"associatedToCharger": true,
"associatedChargerIds": ["string"
]
}

disconnectDevice

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

getHeatingSessions

Get smart heating device historical sessions

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200
400
404

Content type

application/json

[{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"endDateTime": "2019-08-24T14:15:22Z",
"status": "ACTIVE",
"steeringPeriods": {"property1": 0,
"property2": 0
},
"spotPriceAreaId": "SE3",
"timeZone": "Europe/Stockholm"
}
]

getHeatingSchedule

Get smart heating device schedule

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200
400
404

Content type

application/json

{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"steeringPeriods": {"property1": 0,
"property2": 0
},
"spotPriceAreaId": "string"
}

getSessions

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"endDateTime": "2019-08-24T14:15:22Z",
"status": "ACTIVE",
"hourlyCharges": {"property1": 0,
"property2": 0
},
"spotPriceAreaId": "SE3",
"readyTime": "2019-08-24T14:15:22Z",
"timeZone": "Europe/Stockholm"
}
]

getSchedule

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200

Content type

application/json

{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"hourlyCharges": {"property1": 0,
"property2": 0
},
"spotPriceAreaId": "SE3",
"readyTime": "2019-08-24T14:15:22Z",
"timeZone": "Europe/Stockholm"
}

getAuthorizationUrl

Authorizations:

apiKey

Responses

Response samples

200

Content type

application/json

{"url": "string"
}

getOCPPChargerStatus

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200

Content type

application/json

{"statusTimestamp": "2019-08-24T14:15:22Z",
"status": "AVAILABLE",
"errorCode": "string",
"vendorId": "string",
"vendorErrorCode": "string",
"heartbeatTimestamp": "2019-08-24T14:15:22Z",
"measurement": {"timestamp": "2019-08-24T14:15:22Z",
"value": 0,
"unit": "string"
},
"firmwareVersion": "string"
}

getHeatPumpStatus

Get HeatPumpStatus for device

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200
404

Content type

application/json

{"timestamp": "string",
"lastActivityDate": "string",
"connectionStatus": "string",
"hasAlarmed": true,
"roomTemperature": "string",
"exhaustAir": "string",
"compressorTimeFactor": "string"
}

Wallbox API

registerAccount

Provide Wallbox account credentials to be exchanged for tokens which are stored so that Wallbox operations can be done on behalf of the user

Authorizations:

apiKey

query Parameters

object (ContinuationObject)

header Parameters

X-User-Id

required

string

Request Body schema: application/json

username	string
password	string

Responses

Request samples

Payload

Content type

application/json

{"username": "string",
"password": "string"
}

getChargers

Get a list of Wallbox chargers

Authorizations:

apiKey

query Parameters

object (ContinuationObject)

header Parameters

X-User-Id

required

string

Responses

telematica-controller

registerAccount_1

Authorizations:

apiKey

query Parameters

object (ContinuationObject)

header Parameters

X-User-Id

required

string

Request Body schema: application/json

redirectUrl	string <uri>
brand	string
region	string
deviceType	string
brandSubset	Array of strings
excludeBrands	Array of strings
devMode	boolean

Responses

Request samples

Payload

Content type

application/json

{"redirectUrl": "http://example.com",
"brand": "string",
"region": "string",
"deviceType": "string",
"brandSubset": ["string"
],
"excludeBrands": ["string"
],
"devMode": true
}

Prices API

Get spot prices for given area id

Authorizations:

apiKey

path Parameters

areaId

required

string

Example: SE3

spot price area id

query Parameters

startDateTime	string
endDateTime	string

Responses

Response samples

200
404

Content type

application/json

{"2023-01-05T21:00:00Z": 0.0123,
"2023-01-05T22:00:00Z": 0.0234
}

Set spot prices for given area id for testing purposes

Authorizations:

apiKey

path Parameters

areaId

required

string

Example: SE3

spot price area id

Request Body schema: application/json

Hourly energy prices per MWh in Euros

property name*

additional property

number

Responses

Request samples

Payload

Content type

application/json

{"2023-01-05T21:00:00Z": 12.3,
"2023-01-05T22:00:00Z": 23.4
}

Get spot price area id by country code and postal code

Authorizations:

apiKey

query Parameters

countryCode required	string Example: countryCode=SE ISO 3166-1 alpha-2 country code
postalCode required	string Example: postalCode=12346 Postal code

Responses

Response samples

200

Content type

*/*

SE3

Get countries with support for spot price data

Authorizations:

apiKey

Responses

Response samples

200

Content type

application/json

["AT",
"DE",
"SE"
]

OAuth provider API

registerOAuthCode

Authorizations:

apiKey

Responses

redirectToOAuthConnectAuthorizeEndpoint

Authorizations:

apiKey

Responses

device-commands-controller

stopCharging

Stop charging immediately. Smart charging will be switched off for the device.

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

startCharging

Start charging immediately. Smart charging will be switched off for the device.

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Smartcar API

getVehicleStatus_1 Deprecated

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200

Content type

application/json

{"id": "string",
"timestamp": "string",
"soc": 0,
"range": 0,
"chargingStatus": "CHARGING",
"batteryCapacity": 0
}

triggerVehicleStatusUpdate

Trigger smartcar vehicle state update

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

registerAccount_2

Authorizations:

apiKey

header Parameters

x-user-id

required

string

Request Body schema: application/json

authCode	string
redirectUrl	string <uri>

Responses

Request samples

Payload

Content type

application/json

{"authCode": "string",
"redirectUrl": "http://example.com"
}

getVehicleCapabilities

Authorizations:

apiKey

path Parameters

deviceId

required

string

query Parameters

forceRefresh

boolean

Default: false

Responses

getAuthorizationUrl_1

Authorizations:

apiKey

query Parameters

redirectUri required	string
manufacturer required	string
countryCode	string Default: "FI"
mode	string Default: "live" Enum: "live" "simulated" "test"

Responses

Response samples

200

Content type

application/json

{"authorizationUrl": "string"
}

status-controller

fetchDeviceStatus

Authorizations:

apiKey

path Parameters

deviceId

required

string

query Parameters

object (ContinuationObject)

Responses

smartcar-api-capabilities-controller

getSupportedMakes

Authorizations:

apiKey

Responses

getMakeCapabilities

Authorizations:

apiKey

query Parameters

supporting	Array of strings unique Items Enum: "READ_LOCATION" "EXECUTE_START_AND_STOP" "READ_BATTERY_CAPACITY"
not_supporting	Array of strings unique Items Enum: "READ_LOCATION" "EXECUTE_START_AND_STOP" "READ_BATTERY_CAPACITY"

Responses

electrical-utility-providers-controller

getElectricalUtilityProviders

Authorizations:

apiKey

Responses

demand-response-rest-controller

fetchDemandResponse

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Generic Device Status API

getVehicleStatus

Authorizations:

apiKey

path Parameters

deviceId

required

string

Responses

Response samples

200

Content type

application/json

{"id": "string",
"timestamp": "string",
"soc": 0,
"range": 0,
"chargingStatus": "CHARGING",
"batteryCapacity": 0
}