This page is in preview.

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

1

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:

https://<your.auth.url>?connect_token=cot_68541c4c407600f62fd98a97
  • 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.
2

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.

curl --request GET \
  --url https://api.flatpeak.com/connect/account-info/{connect_token} \
  --header 'Authorization: Basic <encoded-value>'
  • The account object contains information about the FlatPeak customer.
  • The credentials object includes auth details, as required by your integration.
3

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.

4

Process customer decision

If the customer consents to share their data:

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

curl --request PATCH \ 
--url 'https://api.flatpeak.com/connect/auth_capture/{connect_token}' \ 
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
    "success": true,
    "auth_data": {
      "access_token": "476dfc58-fd6a-4a32-9483-7dd9b8126c6e",
      "user_prefix": "EYR43EUT-1"
    },
    "postal_address": {
      "address_line1": "1-3",
      "address_line2": "Strand",
      "city": "London",
      "state": "Greater London",
      "post_code": "WC2N 5EH",
      "country_code": "GB"
  },
  "contract_term": {
      "contract_start_date": "2023-01-24T00:00:00Z",
      "contract_end_date": "2024-01-24T00:00:00Z"
  },
}'
  1. Redirect the customer’s browser to the redirect_uri provided in the API response. Upon successful redirection, you will receive an HTTP/1.1 200 OK response.

​
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 submitted during the authorisation step. You can also 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.