CSMS API Migration Guide: v1 → v2

Overview

Dreev-generated identifiers

All resources are now identified by Dreev-internal IDs rather than CSMS identifiers. Your CSMS identifiers are still accepted at ingestion time, and the API returns the mapping so you can correlate them. This creates consistent identifiers across provisioning, charging statistics, and fleet management, regardless of which CSMS the charging station belongs to.

Charging Station concept

v2 introduces a Charging Station entity layered on top of EVSEs, enabling support for charge points with multiple connectors. The platform remains EVSE-centric — each EVSE has its own unique Dreev-generated identifier — which differs from OCPP 2+ where EVSEs only carry numbers relative to their parent Charging Station. Heartbeats are now sent at the Charging Station level, while transactions, measurements, and charging state remain at the EVSE level.

Existing single-EVSE charging stations are unaffected: Dreev uses the same identifier for both the Charging Station and its single EVSE, so no re-provisioning is required for them.

---

General Convention: Identifier Scope

As a rule of thumb, endpoints prefixed with /csms/{csmsId}/ accept your CSMS identifiers as primary keys (e.g. csmsEvseId, csmsTransactionId). Endpoints without that prefix operate on Dreev-internal identifiers exclusively. This convention applies consistently across both the Server and Fleet Management APIs.

In v1, the /csms/{csmsId}/ prefix was the norm for virtually all endpoints. In v2, it is retained only where a CSMS-scoped context is genuinely needed — most endpoints have moved to Dreev-ID-based paths.

---

Base URL

---

Server API (CSMS → Dreev)

Provisioning: EVSEs → Charging Stations

In v1, you registered individual EVSEs. In v2, you register Charging Stations, each declaring their EVSEs upfront. Dreev assigns a Dreev ID to the Charging Station and to each EVSE.

The v2 registration request includes csmsChargingStationId, the charging station model, and the list of EVSEs (each with a csmsEvseId and modelEvseId). The response includes the Dreev-assigned id for the Charging Station and for each EVSE — store these, as all subsequent calls use Dreev IDs.

Heartbeats

Heartbeats move from EVSE-level to Charging Station-level, and the csmsId path parameter is dropped (your OAuth token scopes to your CSMS).

The request body changes from a list of EVSE IDs to a list of Charging Station IDs (Dreev IDs).

Transaction Events

The path and request body structure are unchanged, but all identifiers switch to Dreev IDs.

Key changes in the request body:

• evseId — now a Dreev EVSE ID (not your CSMS EVSE ID)
• vehicleId — now a Dreev vehicle ID (not your CSMS vehicle ID)
• csmsTransactionId — your CSMS transaction ID is still sent, and remains required

The response returns a CsmsTransactionMapping for each transaction start: the Dreev transactionId paired with your csmsTransactionId. Store this mapping — all subsequent calls (charging commands, measurements, charging state) use the Dreev transactionId.

Measurements

The csmsId path parameter is dropped.

Each measurement now references a Dreev transactionId instead of a CSMS transaction ID.

Charging State

The csmsId is dropped from the path; the transaction ID is now a Dreev ID.

Charging Commands (polling)

csmsId is dropped from the path; transaction and EVSE IDs are Dreev IDs.

Transaction History

Vehicles

Registration and lookup paths are simplified; the csmsId is kept only where needed for scoping.

---

Client API (Dreev → CSMS, push mode)

Charging Commands

The pushed commands now use Dreev IDs.

The request body schema changes from EvseChargingCommandV1 / EvseDefaultChargingCommandV1 to EvseChargingCommandV2 / EvseDefaultChargingCommandV2. The transactionId and evseId fields now carry Dreev IDs.

---

Charging Requirements

All charging requirement endpoints previously scoped under /csms/{csmsId}/vehicles/{vehicleId}/... and /csms/{csmsId}/transactions/{transactionId}/... are moved to the dedicated Fleet Management API and use Dreev IDs throughout.

Identification

Identification endpoints move to the Fleet Management API. The key structural change is that badge-to-vehicle mappings are now scoped to a fleet rather than a CSMS, reflecting that a badge may belong to a fleet spanning multiple charging networks.

The fleetId is the Dreev-internal fleet identifier. The evseId and vehicleId are Dreev IDs.

---

Migration Process

Dreev maintains both v1 and v2 simultaneously to give integrators time to migrate. There is no hard cutoff date — you can run both versions in parallel, and for a smooth migration you should: v1 handles traffic while you progressively switch subsystems to v2.

The recommended migration sequence is as follows.

Step 1 — Fetch and store Dreev internal IDs

While still on v1, retrieve and persist the Dreev-internal identifiers for all your provisioned resources. No downtime or pause is needed at this stage. The v2 Server API GET endpoints return both your CSMS identifiers and Dreev-internal IDs in the same response.

• Charging Stations & EVSEs — call GET /csms/{csmsId}/charging-stations to retrieve Charging Stations with their Dreev IDs and the Dreev EVSE ID for each connector. For existing single-EVSE charging stations, the Charging Station ID and EVSE ID are the same.
• Vehicles — call GET /csms/{csmsId}/vehicles to retrieve vehicles and their Dreev vehicleId.
• In-flight transactions — the v2 transaction events response returns the csmsTransactionId ↔ transactionId mapping for every new transaction going forward. For transactions already open at migration time, call GET /evses/{evseId}/transactions to browse transaction history and retrieve the Dreev transactionId for each open transaction.

Step 2 — Switch provisioning to v2 (if applicable)

This step only applies to clients that dynamically provision Charging Stations via the API. If charging stations are provisioned manually by Dreev, skip this step.

Start registering new Charging Stations via POST /csms/{csmsId}/charging-stations instead of the v1 EVSE endpoint. Store the Dreev IDs returned in the response. Existing already-provisioned stations require no action.

Step 3 — Switch transaction events to v2

Update POST /csms/{csmsId}/transaction-events to send Dreev EVSE IDs and vehicle IDs. From this point on, store the transactionId returned in the response mapping for every new transaction start.

No pause in transaction event sending is needed. New transactions started after step 3 will naturally carry Dreev IDs; in-flight transactions whose Dreev IDs were resolved in step 1 can be completed using v1 until they close.

Step 4 — Switch measurements, charging state, charging commands, and heartbeats

Migrate all remaining high-frequency calls at once, using the Dreev IDs stored in previous steps:

• POST /transaction-measurements
• POST /transactions/{transactionId}/charging-states
• GET /transactions/{transactionId}/charging-commands/latest
• GET /evses/{evseId}/default-charging-commands/latest
• POST /charging-station-heartbeats (using Dreev Charging Station IDs)

Step 5 — Switch Fleet Management endpoints

Migrate charging requirements, identification, and trips endpoints to the Fleet Management API, replacing CSMS-scoped paths with Dreev-ID-based paths as described in the Charging Requirements section above.

Step 6 — Switch Client API (push mode) (requires Dreev intervention)

If you implement the Client API (Dreev pushing commands to your CSMS), update your endpoint implementations to accept EvseChargingCommandV2 / EvseDefaultChargingCommandV2 payloads carrying Dreev IDs, and implement the new POST /charging-errors and POST /charging-stations callbacks.

Once your v2 endpoints are live and tested, contact Dreev to trigger the switch. Dreev will then start pushing v2 payloads to your CSMS. Make sure your v2 endpoints are fully deployed before doing so — the switch takes effect immediately.

Tip: To avoid having to synchronise your deployment with Dreev's config change, consider deploying your v2 Client API under a different domain than v1. Both versions can then be live simultaneously, and when you're ready, a single Dreev-side config update switches both the target URL and the payload version atomically. This also makes rollback straightforward.