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 depends 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. Tariff access authorisation

1

Receive request

Your customers typically interact with Flatpeak via their manufacturer’s device 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:
https://<your authentication URI>?connect_token=cot_68541c4c407600f62fd98a97
The connect_token is a unique, time-limited token used to authenticate the session.
2

Obtain session context

Call the Flatpeak API to retrieve the session context. The API authentication credentials required for this request will be provided by the Flatpeak team during onboarding.
curl --request GET \
  --url https://api.flatpeak.com/connect/session/{connect_token} \
  --header 'Authorization: Basic <encoded-value>'
The account object contains Flatpeak customer details, including links to their logo, Terms of Service, Support and Privacy Policy. Use this information on your Sharing Consent screen, as described later in this article.The redirect_uri field contains your authentication URI to which the user was redirected. It is included for audit purposes.The connect_web_uri field conlains URI where you will redirect customer’s session after they completed interaction with your service.
3

Identify your customer

Present a screen where customers authenticate using your system’s credentials:

Login screen

If the customer declines or cannot log in, skip to the Submit session status step below.
4

Obtain tariff sharing consent

Request your customer’s consent to allow a specific third party to access their tariff data. Use contents of the account object from the Session Context response to populate this consent screen.

Consent screen

If the customer declines to consent, skip to the Submit session status step below.
5

Submit session status to Flatpeak API

If the customer declines or cannot log in, notify the Flatpeak API:
curl --request PUT \
--url 'https://api.flatpeak.com/connect/consent_capture/{connect_token}' \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "DISMISS_LOGIN"
}'
6

Redirect customer back to Flatpeak

Once you’ve submitted the session status to the Flatpeak API, redirect the customer’s browser to the connect_web_uri provided in the Session Context response, append the connect_token.
https://auth.direct.flatpeak.com?connect_token=cot_68541c4c407600f62fd98a97

​
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.