HomeGuidesAPI ReferenceChangelog
Terms of Use
Guides
Terms of Use

API functional components

Our API is divided into three functional components - Resources, Actions, and Notifications. By combining different components and their respective subsets, you can build flexible workflows, allowing you to differentiate and customize your EV charging portfolio.

a. Resources

Resources serve as the foundation of our API. With resources, you can Create/Read/Update/Delete (CRUD) every object/asset in the EV charging flow. Each resource comes with its unique set of properties and meta-data.

  • Location - Physical reference with end-user-facing information like POI
  • Charge point - Charge point-related data
  • EVSE - connector-related data
  • User - end-customer/EV driver
  • ID tag - authorization medium - RFID card or MAC address
  • Tariff - pricing rule combining description for end users, pricing type and applicability to a specific group of users
  • Tariff group - grouping of several Tariffs that allows multi-tiered pricing
  • Session - collection of all charging data related to a single session / CDR
  • Transaction - payment-related data about a single session used for payment processing
  • Subscriptions - pre or post-paid plan for end-users
  • Partners/B2B partner - Roaming operator, fleet, site hosts, etc.
  • Electricity Rates - pricing table used for electricity cost tracking or dynamic pricing
  • Circuit - Charge Points grouped together for the purpose of load balancing via a virtual algorithm using OCPP smart charging profiles
  • Vendor error codes - human-readable translation of vendor-specific error codes

๐Ÿ“˜

NB!

For the extensive list of resources, please check the API reference.

b. Actions

That's where to start/stop a session, unlock EVSE, or activate a user subscription. Here are a couple of examples:

1. Main Charge Point Actions

  • Start Charging Session - Remote Start command, enabling you to programmatically initiate a session by specifying chargePoint ID, EVSE ID, as well as an optional user ID and/or Payment Method.
  • Stop Charging Session - Remote Stop command, concluding the charging session. You need to specify the Charge Point ID and Session ID. You can initiate a Force Stop optionally, which will immediately end the session, regardless of whether a confirmation is received from the Charging Station.
  • Charge Point Reserve - The reservation command sets the Charge Point status to reserved by passing chargePoint ID, EVSE ID, and userId as required parameters.
  • Charge Point Unlock - the Unlock command triggers the plug to be unlocked on the Charge Point side. This is only applicable for Charging Stations with socket setup.
  • Charge Point Reset - the command triggers a remote reset sequence for the charge point, which could be performed for the internal controller only or as a power cycle for the complete hardware (soft vs. hard). The result of this command depends heavily on the specific hardware vendor (some vendors do not differ between soft and hard reset sequences).
  • Set charging Profile - manage and change Transaction Profiles remotely by passing the evseNetworkId and chargePointID. You're able to toggle stack level, chargingProfilePurpose (ChargePointMaxProfile, TxDefaultProfile,TxProfile) as well as chargingProfileKind (Absolute, Recurring and Relative). Another mandatory object to the body of your request would be the charging schedule, where you can set the active time periods for the respective TxProfile.

2. Main User Actions

  • Change User Status - set user status to enabled or disabled.
  • Activate/Cancel Subscriptions - set of endpoints enabling you to manage user subscriptions to specific plans, auto-renewal rules, or cancellations.
  • Add Balance - remotely add a specific amount to the user's balance ledger.
  • Apply Custom Fee - charge user's balance ledger.
  • Redeem Voucher - pay off an existing voucher.

๐Ÿ“˜

NB!

For the extensive list of resources, please check the API reference.

c. Notifications

Webhook notifications allow you to listen to the major events on the platform and help you create a real-time system. Some notifications are similar to the OCPP messages, but others are platform-specific. Here are some important examples of the Notification Callback library:

  • Boot Notification Callback - notifies in the event of a Boot Notification from the charging station
  • Hardware Status Notification Callback - triggered in the event of a new hardware status on the Charging Station end: available, preparing, charging, suspendedEVSE, suspendedEV, finishing, reserved, unavailable, faulted
  • Network Status Notification Callback - triggered in the event of a network status change for the Charging Station: never connected, available, temporarily unavailable, long-term unavailable
  • Session Start and Stop Notification Callback - triggered in the event of a session initiation or session conclusion
  • Session Update Notification Callback - triggered in the event of a status change for an existing (ongoing) charging session. Statuses vary across: unknown, pending, active, finished, failed or expired and the notification can also be accompanied by a reason, such as a timeout, working hours exceeded, schedule completed, balance exceeded, etc.
  • Session Meter Values Notification Callback - triggered upon every Meter Value submission event from the Charging station, enabling the near real-time tracking of Energy Consumed, State Of Charge, Current Consumed, Current Offered, Voltage, Power Offered in the respective units.
  • Reservation Status Changed Callback - triggered in the event of a status change for an existing reservation: active, expired, canceled, done
  • User Balance Changed Callback - triggered in the event of a balance amount change, respectively debit or credit amount, updated balance amount, currency, userId, timestamp, and more.
  • User Subscription Changed Callback - triggered in the event of changes to a subscription plan for a particular user: active, canceled, expired

๐Ÿ“˜

NB!

For the extensive list of resources, please check the notifications in the API reference page.