Skip to main content
Flatpeak Connect is the customer-facing entry point to the Flatpeak platform. It allows your app to enable customers to link their electricity tariff, so your backend can access energy prices.

View Quickstart

New to Flatpeak? Start with the Quickstart guide before continuing.
 Connect can be integrated in two main ways:
  • Clone our reference implementation and embed it into your app via WebView.
  • Build the necessary pages in your app using preferred framework and the Flatpeak API (recommended).
  • WebView integration
  • API integration
Use this guide to integrate Flatpeak’s Connect into your app by embedding it via WebView.
WebView
1

Clone Connect web app

git clone https://github.com/flat-peak/flatpeak-connect-web.git
cd flatpeak-connect-web
npm install
You will need to host the web app on your servers for production.For now, you can simply run it on your computer.
2

Configure environment variables

export FLATPEAK_CONNECT_URL=https://connect.flatpeak.com
Ensure this is set correctly for your environment. Adjust for Windows-based shells if needed.
3

Test run the Connect app

npm run dev
A local preview will be available at http://localhost:7070.
You will see an error. This is because you have not provided a Connect token. Ignore the error for now and continue following this guide.
4

Subscribe to Connect session events

Your system needs to be notified when a customer completes the Connect flow so it can start retrieving their electricity prices and using other energy intelligence endpoints.
Flatpeak Dashboard Webhooks
Subscribe to connect.session.complete events via a webhook:
  1. Open Flatpeak Dashboard
  2. Select Webhooks in the main menu
  3. In Endpoint URL, enter the address where you want to receive webhook events
  4. Click Events and select connect.session.complete
  5. Set the selector to Live data or Test data, depending on API key you are using
  6. Click Create to start sending events to your webhook destination
5

Create a Connect token

Single-use Connect tokens enable secure access to Connect API endpoints while keeping API keys away from the frontend.
  1. First, authenticate to the API by calling authentication endpoint.
  2. Next, call the create-connect-token endpoint to create a connect_token.
curl --request POST \
--url https://api.flatpeak.com/connect/tariff/token \
--header 'Authorization: Bearer <bearer_token>' \
--header 'Content-Type: application/json' \
--data '{
  "connect_url": "<URL to return from external resources back to your app>",
  "callback_uri": "<URL to redirect after Connect flow completes>",
  "postal_address": {
    "address_line1": "1-3",
    "address_line2": "Strand",
    "city": "London",
    "state": "Greater London",
    "post_code": "WC2N 5EH",
    "country_code": "GB"
  }
}'
6

Launch the Connect app

In your browser, open: http://localhost:7070?fp_cot=cot_***, replacing cot_*** with the connect_token:
In production, customers will launch Connect directly from your app. Your backend should create Connect tokens on demand and pass them to the app.
7

Customer will interact with Connect flow

Connect guides customers through a short flow to share their tariff. It automatically chooses the best method based on provider APIs, data-sharing rules, and usage patterns across Flatpeak.
To test Connect flow, use your own account from any supported energy provider. If you don’t have access to one, contact support for a test account.
Learn more about Connect flow architecture, markets and provider integrations coverage.
8

Handle session completion

  1. When the customer successfully completes a session with Connect, you will receive a webhook to the destination you specified earlier:
Example webhook payload
{
  "id": "evt_66167787c1652b3fbeba5f01",
  "object": "event",
  "type": "connect.session.complete",
  "data": {
    "id": "cot_6587fa4362341be5b524de3b",
    "object": "connect_token",
    "location_id": "loc_641b90b758fb8e6293716e40",
    "price_available": true

  }
}
  1. The location_id is a permanent identifier for your customer’s address. Store it in your database as a reference to the customer’s address. You will use it to fetch electricity prices and access other energy intelligence endpoints. You can also re-request this ID by calling retrieve-connect-token endpoint.
curl --request GET \
--url 'https://api.flatpeak.com/connect/tariff/token?connect_token=cot_6587fa4362341be5b524de3b' \
--header 'Authorization: Bearer <token>'
9

Provide an option for customers to change tariff connection

To enable customers to modify or remove their tariff connection, see the Tariff Settings Page guide. It explains how to build UI controls that let them view, reconnect, disconnect, or adjust their tariff — including connecting an export tariff.
In short, you’ll need to implement passing the location_id when creating Connect tokens. This will launch Connect in the context of the existing tariff connection for that location.

​
Tip for embedding

When embedding Connect in your app, launch it in a modal or bottom sheet (iOS/Android) to prevent layout issues—especially on devices with notches or cutouts.
This will keep the interface clean and ensure all elements remain visible.

​
Next steps

Your systems can now access: