Charging stations

A charging station is one of the main entities in be.ENERGISED. The charging stations id will be used for different other calls as URL parameter (e.g. maintenance windows).

Reading

Charging stations can be accessed via the charging_stations GET endpoint. This endpoint will return a list of all visible stations in be.ENERGISED.

The list endpoint is using offset pagination.

curl --location --request GET \
'https://<slug>.beenergised.cloud/api/cpoapi/v1/charging_stations/' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json'

Creating

New charging stations can be created via the charging_stations POST endpoint.

curl --location --request POST \
'https://<slug>.beenergised.cloud/api/cpoapi/v1/charging_stations/' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json' \
--data '{
  "label": "Station A",
  "chargeBoxIdentity": "ABC123",
  "modelId": 1,
  "companyUuid": "company-uuid-here",
  "timeZone": "Europe/Berlin"
}'

Required Parameters

  • label (string): Label visible in the UI.

  • chargeBoxIdentity (string): Charge box identity used as main identifier in the OCPP connection. Must be unique.

  • modelId (integer): ID of the charging station model.

  • companyUuid (string): UUID of the company (entity) the station is connected to.

  • timeZone (string): The timezone of the station, e.g. Europe/Berlin.

Optional Parameters

  • publicDisplayName (string): Name shown in external systems like apps.

  • iccid (string): ICCID received by the station during the BootNotification.

  • imsi (string): IMSI received by the station during the BootNotification.

  • serialnumber (string): Serial number received by the station during the BootNotification.

  • address (object): Address information for the station.

  • geolocation (object): Geographic location of the station.

  • technicianUserId (integer, optional): ID of the technician to assign to this station. The technician must belong to a company in the same mandant as the station. If not provided, no technician is assigned.

  • useOcpp (boolean, optional): Whether the station uses OCPP. Defaults to true on create.

  • enabledRoamingInterfaces (array of strings, optional): List of roaming partner slug names (as returned by the GET endpoint) that should be active for this station. Providing the field reconciles the assignment: slugs not in the list are removed, new slugs are activated (which pushes the activation to the external roaming partner). Omit the field entirely to leave the current assignment untouched; supply an empty array to remove all assignments.

  • locationId (string, optional): UUID of the location (as returned by GET /locations) the station should be assigned to. Providing the field moves the station in cposvc-station-list: any previous assignment is removed and the new one is added. Supply null to unassign; omit the field entirely to leave the current assignment untouched. Equivalent to calling PUT /locations/:uuid/stations separately.

Assigning a Technician

To assign a technician when creating a station, first retrieve the available technicians:

curl --location --request GET \
'https://<slug>.beenergised.cloud/api/cpoapi/v1/technicians/?limit=50' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json'

Then use the technician’s id in the creation request:

curl --location --request POST \
'https://<slug>.beenergised.cloud/api/cpoapi/v1/charging_stations/' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json' \
--data '{
  "label": "Station B",
  "chargeBoxIdentity": "DEF456",
  "modelId": 1,
  "companyUuid": "company-uuid-here",
  "timeZone": "Europe/Berlin",
  "technicianUserId": 42
}'

For more information about available technicians, see the Technicians section.

Response fields

The GET responses include every field accepted by POST / PUT so the returned object can be modified and PUT back without external lookups:

  • address and geolocation mirror the write-side objects. Because the write path stores addressLine1 + “ “ + addressLine2 concatenated, the response returns the combined value in addressLine1 with addressLine2 set to null.

  • useOcpp, locationId and technicianUserId are returned as their current stored values.

  • enabledRoamingInterfaces is returned only on the detail endpoint (GET /charging_stations/:cpuuid) as an array of roaming partner slug names. It is omitted from the list endpoint for performance reasons.

Directions

Directions are short wayfinding texts telling a driver how to find the station once they have arrived on site — for example “underground car park, level -1, behind the lift”. A station can hold one direction per language.

The language is the identifier of a direction. It is a two-letter ISO 639-1 code and travels in the URL path, so all three verbs address a direction the same way:

Operation

Endpoint

List all directions

GET /charging_stations/{uuid}/directions

Add or update one language

PUT /charging_stations/{uuid}/directions/{language}

Remove one language

DELETE /charging_stations/{uuid}/directions/{language}

Reading directions

Returns every direction of the station, ordered by language code. A station without directions returns an empty attributes list rather than a 404.

curl --location --request GET \
'https://<slug>.beenergised.cloud/api/cpoapi/v1/charging_stations/<uuid>/directions' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json'

{
  "id": "<uuid>",
  "type": "station_directions",
  "attributes": [
    { "language": "de", "text": "Tiefgarage Ebene -1, hinten links neben dem Aufzug" },
    { "language": "en", "text": "Underground car park, level -1, behind the lift" }
  ]
}

Writing a direction

The request body carries only text — the language is taken from the path, not from the body. A PUT for a language that already exists replaces its text instead of adding a second entry, so the call is safe to repeat.

curl --location --request PUT \
'https://<slug>.beenergised.cloud/api/cpoapi/v1/charging_stations/<uuid>/directions/de' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json' \
--data '{
  "text": "Tiefgarage Ebene -1, hinten links neben dem Aufzug"
}'

The response returns the single direction that was written:

{
  "id": "<uuid>",
  "type": "station_directions",
  "attributes": { "language": "de", "text": "Tiefgarage Ebene -1, hinten links neben dem Aufzug" }
}

Parameters

  • language (path): Two-letter ISO 639-1 code, e.g. de, en, fr. Case-insensitive — DE and de address the same direction. A code that is not two letters is rejected with 400. A path segment containing anything other than letters, digits, - or _ does not match the route at all and comes back as 404.

    PUT additionally requires the code to be one of the languages the platform supports, and rejects anything else with 400. This is the same set the portal’s direction editor offers, so that a direction written here can also be read and corrected in the UI. The supported set does not cover every ISO 639-1 code; if a language you need is missing, ask your contact at has·to·be to have it added.

    DELETE is deliberately not restricted this way: directions written before this rule existed may carry a code that is no longer accepted, and they have to stay removable.

  • text (body, string): The direction text. Required, trimmed, must not be blank, and at most 512 characters.

Deleting a direction

Removes the direction for one language and leaves the other languages untouched. Deleting a language that is not set is a no-op and also returns 200.

curl --location --request DELETE \
'https://<slug>.beenergised.cloud/api/cpoapi/v1/charging_stations/<uuid>/directions/de' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json'

Limitations

  • These are not the directions exported over OCPI. The station detail page in be.ENERGISED has a separate “Directions” field on the Marketing tab, and that is the one included in the OCPI location export to roaming partners. The directions managed here are stored separately and are currently read back only through this API. Maintaining both on the same station will make them diverge.

  • Roaming stations are not supported. All three verbs return 404 for a roaming station. Their directions are maintained by the roaming import, which replaces them wholesale on every pull, so anything written through this API would be discarded again.

  • The text is limited to the Windows-1252 character repertoire. Western European text is fine, including umlauts, accents, typographic quotes and the euro sign. Characters outside it — Greek, Cyrillic, Polish, Czech, Hungarian, Turkish and Croatian among others — are rejected with a 400 rather than stored incorrectly.