FlatPeak integration for energy providers
This document outlines how an energy provider can integrate with FlatPeak, enabling a wide range of customer assets to automatically follow their contracted tariffs, no matter how complex or dynamic those tariffs are.
If you represent an energy provider interested in integrating with FlatPeak, please complete this form (or email integrations@flatpeak.com). We will be in touch to arrange a call to discuss next steps.
Time and scope
The time and effort required to integrate with FlatPeak depend on the configuration of your systems. Typically, an integration can be completed in 2-4 weeks, with most or all work done by our dev team, followed by 2 weeks of testing.
Integration process
FlatPeak would typically build a bespoke integration with your systems, enabling compatibility with any authentication method and data format. Ideally, authentication is handled via OAuth using long-lived tokens; the customer tariff is retrieved in whatever format your system provides.
A standard integration involves two main parts:
1. Authorization
Receive request
Your customers typically interact with FlatPeak via their manufacturer’s device’s companion app, which integrates our APIs. When they select you as their provider, we instruct the companion app to redirect the browser to your authentication URI:
- The
connect_token
is a unique, time-limited token that represents and authenticates this session. - The
redirect_uri
is where you must redirect the customer’s browser after they complete authorisation with your system.
Obtain session context
Call the FlatPeak API to retrieve the session context. API authentication credentials will be provided by the FlatPeak team during the onboarding process.
- The
account
object contains information about the FlatPeak customer. - The
credentials
object includes auth details, as required by your integration.
Render authentication views
Use the data from previous steps to implement an authentication flow similar to the example below. We recommend providing an escape option that allows the customer to cancel the login process. In this case, redirect them to the redirect_uri
with an appropriate failure code.
Process customer decision
If the customer consents to share their data:
- Submit the required account access details to the FlatPeak API. The data object must contain all necessary credentials for FlatPeak to access the customer’s account and retrieve their tariff in headless mode — e.g. access token or other required fields.
-
The
auth_data
object can include any number of key-value pairs required to access the customer’s account and retrieve their tariff. FlatPeak will implement custom logic to fetch this data based on your integration requirements. -
The optional
postal_address
object may include the customer’s postal address. This is used to determine the applicable market region and/or network fees, if relevant. -
The optional
contract_term
object includes information about the customer’s contract start and end dates. This information will be used to determine the date from when the customer tariff must be synchronised and to remind the customer to re-establish the tariff connection on the contract renewal date.
- Redirect the customer’s browser to the
redirect_uri
, appendconnect_token
as query parameter.
If the customer consents to share their data:
- Submit the required account access details to the FlatPeak API. The data object must contain all necessary credentials for FlatPeak to access the customer’s account and retrieve their tariff in headless mode — e.g. access token or other required fields.
-
The
auth_data
object can include any number of key-value pairs required to access the customer’s account and retrieve their tariff. FlatPeak will implement custom logic to fetch this data based on your integration requirements. -
The optional
postal_address
object may include the customer’s postal address. This is used to determine the applicable market region and/or network fees, if relevant. -
The optional
contract_term
object includes information about the customer’s contract start and end dates. This information will be used to determine the date from when the customer tariff must be synchronised and to remind the customer to re-establish the tariff connection on the contract renewal date.
- Redirect the customer’s browser to the
redirect_uri
, appendconnect_token
as query parameter.
- If the customer declines to login, is unable to login or declines to share tariff data, submit information about the customer’s decision to FlatPeak API:
- Submit
DISMISS_LOGIN
action value when customer did not want to login. - Submit
DISMISS_CONSENT
action value when customer did not agree to share data. _ SubmitERROR
value in all other cases.
- Redirect the customer’s browser to the
redirect_uri
, appendconnect_token
as query parameter.
2. Tariff polling
FlatPeak will implement custom logic to fetch tariff data from your customer’s account based on your integration requirements, using the credentials provided in the auth_data
object to authenticate requests.
This request shall retrieve the customer’s tariff, and we expect the response to include the following objects (in your own format):
- Customer tariff – include tariff data covering at least the next 24 hours.
- Contract Start Date – used to backfill tariff data for historical reporting.
- Contract End Date (optional) – used to trigger reminders for the customer to reconnect or update their tariff before it expires.
FlatPeak polls the endpoint regularly, typically every 1–2 days, to retrieve the latest tariff data. You can define the allowed polling frequency and specify the token renewal mechanism.
Not ready to integrate?
If your organisation isn’t ready to integrate with FlatPeak, we would still love to include your tariffs in our library. This helps your customers easily select their tariff when enabling energy cost features on their devices. Please contact our team via the link at the top of this page to arrange an introductory call.