Skip to main content
Version: 1.0.0

PowerBox API

The PowerBox API is the integration surface between a utility's back-office systems and the EnergyGrid platform. It carries the two flows a utility partner needs to wire up before customers can use any EnergyGrid-powered hardware or app:

  • Customer synchronisation — push customer accounts, service addresses (Premises), and meter configurations from the utility Customer Information System (CIS) into EnergyGrid.
  • Hardware binding — link a DataBridge or SmartLink device to its target Advanced Metering Infrastructure (AMI) meter over the utility's wireless mesh radio (Home Area Network).

This page is the entry point. Follow the operations in the sidebar for the full request/response contract, schema definitions, and error semantics.

Audience​

This API is intended for utility backend engineers integrating their CIS and AMI head-end systems with EnergyGrid. It is not a public consumer API.

Authentication​

All endpoints require an OAuth 2.0 Bearer token obtained from the utility's identity provider. Tokens are short-lived (typically one hour) and must be refreshed via the utility IDP — EnergyGrid does not issue tokens. Pass the token in the Authorization header as Bearer <token>. See the Integration Guide — Configure authentication (OAuth) for the end-to-end exchange.

Base URL​

All requests are made against the production base URL, scoped by API version:

https://api.energygrid.example/v1

A staging environment is available for integration testing — see the Servers dropdown on each operation page.

Conventions​

  • Content type. Requests and responses use application/json unless otherwise noted.
  • Identifiers. Customer identifiers (clientId), Premise identifiers (externalSiteId), and Meter identifiers (meterId) are opaque strings owned by the utility CIS. EnergyGrid does not generate them.
  • Account status. The AcctStatus field uses the utility CIS encoding (A = Active, C = Closed, S = Suspended). EnergyGrid mirrors the value rather than translating it.
  • Idempotency. Customer sync (POST /powerbox/customer) is idempotent on clientId — repeating the call with the same payload is safe. Hardware binding (POST /powerbox/bind) is not idempotent; check actionCode and the meter's current bind state before retrying.
  • Errors. Errors return the relevant 4xx status code with no body. Reason codes are derived from the status: 400 invalid payload, 401 invalid or expired token, 403 account locked or closed, 404 unknown identifier.

Versioning​

The API is versioned via the URL path (/v1). Breaking changes ship under a new major version with at least 90 days of overlap. Non-breaking additions (new optional fields, new enum values on extensible enums) ship within the current version.

Sample​

This specification is published as a portfolio sample. The contracts, schemas, and conventions are representative of the kind of utility integration API that EnergyGrid (a fictional platform documented end-to-end on this site) would expose. The hostnames are illustrative and do not resolve.

Authentication​

OAuth 2.0 Bearer token from the Utility IDP

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT

Contact

Leandro Gabriel — Technical Writer: lgos99921@gmail.com

URL: https://www.linkedin.com/in/leandro-gabriel-8aab31167/

License

MIT