Charge box and EVSE management

Managing your charging infrastructure remotely is essential for efficient operations, troubleshooting, and delivering seamless driver experiences. With Spirii's API, you can control charge boxes through remote commands that enable restarts, session management, and connector unlocking—all without physical site visits.

Retrieving charge boxes

You can retrieve charge box information as a list or per entity.

List all charge boxes

Use GET /chargeboxes to retrieve a list of all charge boxes across your network. This endpoint supports filtering and pagination to help you manage large deployments efficiently.

Use limit and NextPageCursor parameters to navigate through results.

Fetch a single charge box

Use GET /chargeboxes/:id to retrieve detailed information about a specific charge box.

The response includes comprehensive data, including the charge box model, firmware version, operational status, parent location, associated EVSEs and connectors, network connectivity details, and configuration settings.

Supported charge box models

Use GET /chargeboxes/models to retrieve a list of validated charge box models that are supported and tested on the Spirii platform.

Each model entry includes the vendor, model name, and description, and whether it’s validated for firmware management and plug & charge.

Creating charge boxes

Use POST /chargeboxes to add a new charge box to your network.

The API reference contains the complete list of required fields, data examples, and valid options. Providing accurate model and connectivity information ensures smooth onboarding when the charge box first connects to the platform.

Upon creation, the charge box will have an operational status of Pending until it successfully connects to the platform and completes its initial configuration exchange.

Deleting charge boxes

Use DELETE /chargeboxes/:id to remove a charge box from your network. This action performs a soft delete, meaning the charge box data is retained in the system but marked as inactive.

Important: You must first ensure the charge box has no active charging sessions before deletion.

Reset & Reboot

Understanding how to restart charge boxes properly is critical for maintenance, troubleshooting, and applying configuration changes.

Reset vs. Reboot:

• Reset: The command you send to instruct a charge box to restart
• Reboot: The actual restart process that occurs, whether triggered by your command or automatically (e.g., firmware updates, power cycles)

Sending Reset commands

Soft Reset (recommended) performs a graceful restart with proper session handling. Only the software restarts (hardware remains powered), taking approximately 30-60 seconds. All queued data and configurations are preserved. Use this for configuration changes, planned maintenance, or troubleshooting when drivers may be actively charging.

Hard Reset (use sparingly) forces an immediate full hardware reboot, taking approximately 1-3 minutes with risk of data loss. Use only when the charge box is unresponsive or Soft Reset has failed.

Always attempt Soft Reset first. Hard Reset should only be used as a last resort.

Applying these commands

Most charge boxes retain configuration settings, connector availability, local authorisation lists, and charging profiles after reboots. Verify this with your specific charge box documentation. Active charging sessions, network connections, and temporary cached data are reset and must be re-established.

In most cases, resetting and rebooting will interrupt and end any active transaction.

Typical use cases

Generally, resets are performed by NOC team to alleviate issues with a charger or a support team assisting a driver as a last resort.

Soft Reset Use Cases A soft reset typically involves restarting the charge point's software components without interrupting power to the hardware. This can be useful in several scenarios:

1. Non-severe communication issues: If the charge point is experiencing communication issues with the central server (e.g., not sending or receiving messages properly), a soft reset can help re-establish the WebSocket connection.
2. Configuration Changes: When configuration settings are changed remotely, a soft reset is often needed be used to ensure those changes take effect immediately. This can be seen when a charger responds with RebootRequired to a configuration change.

Hard Reset Use Cases A hard reset involves completely powering down the charge point, which often requires the hardware to restart. This is more disruptive but can be necessary in certain situations:

1. Hardware Malfunction/Unresponsive Unit/Critical Errors: If the charge point's hardware encounters critical failures (e.g., unable to communicate, hardware locks up), a hard reset may be the only way to restore functionality

Remote Start Transaction

The Remote Start Transaction command enables you to initiate a charging session remotely, either before or after the vehicle is plugged in.

When you send the request, you specify the connector ID and authorisation identifier (idTag/Token/charge key). The charge box changes its status to Preparing immediately, even if no vehicle is connected yet. The ConnectionTimeOut parameter defines how long the charge box will wait for a vehicle to be plugged in before reverting to Available status.

Typical use cases

Remote start is the only way to authorize a charging session without physically interacting with the charger (which would typically be RFID/Credit card). This is used for starting charging with first-party apps, third party apps, or through a platform such as Spirii Connect. Using a platform is an essential tool for support teams to assist drivers on-site who have issues initiating the session.

Remote Stop Transaction

The Remote Stop Transaction command allows you to end an ongoing charging session remotely.

Send a Remote Stop Transaction request with the transactionId of the active session. The charge box responds with Accepted or Rejected status.

Important: Remote Start and Remote Stop commands trigger the standard Start Transaction and Stop Transaction messages from the charge box, ensuring accurate billing and session recording.

Typical use cases

Remote stop is less commonly used than remote start, since a session can always be stopped/deauthorised by unplugging the vehicle. However, it can be a useful tool for support teams for manually forcing a session to stop in case it is stuck.

Unlock Connector

The Unlock Connector command allows you to remotely release a connector lock, typically used to assist drivers experiencing cable disconnection issues.

When you send an Unlock Connector request with a specific connector ID, the charge box attempts to unlock the connector mechanism. If a transaction is active, the charge box will first complete the transaction before unlocking.

Compatibility notes:

• Only works with charge boxes fitted with AC sockets that have electronic locks
• CHAdeMO connectors: The charge box controls the lock, so unlocking should succeed
• Type 2 and CCS connectors: The vehicle controls the lock, so unlocking may not always succeed

Not all charge box manufacturers fully support this functionality, so verify behaviour with your specific hardware.

Typical use cases

This is mostly relevant for support teams to use with AC chargers with a socket where customers bring their own cable, since ChadeMO is rarely used these days.

Specifically, it is relevant when the customer has unlocked the cable from the vehicle side and the cable remains stuck in the charger socket. By using this unlock command, a support team is able to try to force the locking mechanism to unlatch.

Managing EVSEs

EVSEs (Electric Vehicle Supply Equipment) represent the individual electrical circuits within a charge box—each capable of delivering power to one vehicle at a time. A single charge box can contain multiple EVSEs, each with its own connectors and power delivery capabilities. You can retrieve, update, and manage EVSE settings through dedicated endpoints.

Retrieving EVSE information

Use GET /evses to retrieve a list of all EVSEs across your network, or GET /evses/:id to fetch details about a specific EVSE by passing its unique ID as a parameter.

Each EVSE response includes key operational data such as current status, connector details (plug type, power type, maximum power), assigned tariff, and the parent charge box relationship.

This visibility enables CPOs to build custom monitoring and alerting solutions for their fleet management needs—such as tracking equipment performance, detecting issues, or managing maintenance. CPOs can implement alerts based on their specific operational requirements rather than relying on generic tools.

Updating EVSE settings

Use PATCH /evses/:uid/connectors/:id to update specific EVSE properties, such as maximum power output, referred to as maxElectricPower in the API, and connector type, referred to as standard in the API, according to the OCPI specification. This allows you to modify individual EVSE configurations without affecting other EVSEs on the same charge box.

Changing connector availability

Use POST /evses/:uid/connectors/:id/change-availability to change the OCPP availability status of a specific EVSE or connector. This is particularly useful when performing connector maintenance or temporarily taking a charging point out of service without affecting the entire charge box.

Next steps

By mastering charge box actions, you gain better remote control over your charging infrastructure—enabling efficient maintenance, rapid troubleshooting, and responsive customer support without site visits.

Explore the API Reference for these commands, or contact our support team for guidance on implementing remote operations in your workflow.