Get up and running fast with our open-source reference implementation of FlatPeak API for your app. Clone, embed into your app view WebView and deploy in hours.
If you followed the Quickstart guide, some steps below may already be complete.
1

Clone our repo and install the required dependencies

git clone https://github.com/flat-peak/flatpeak-connect-web.git
cd flatpeak-connect-web
npm install
2

Set the environment variables

export FLATPEAK_CONNECT_URL=https://connect.flatpeak.com
If you are on Windows, ensure you appropriately set env variables for your shell.
3

Run locally

npm run dev
A local preview will be available at http://localhost:7070.
Your browser will redirect to an error page. This is because you have not provided a Connect token. Ignore this error and continue following this guide.
4

Obtain a token to access Connect

FlatPeak implements a single-use session token to provide access to Connect API endpoints, so you don’t need to expose API keys to your customer-facing app
  1. Get bearer token from create-a-bearer-token endpoint.
  2. Make a request to create-connect-token to obtain a connect token endpoint. 
    curl --request POST \
--url https://api.flatpeak.com/connect/tariff/token \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "connect_web_uri": "http://localhost:7070",
  "callback_uri": "<any service that can receive webhooks>",
  "postal_address": {
    "country_code": "GB"
  }
}'
5

Run the app

On your computer, where you already have FlatPeak connect code running locally, open: http://localhost:7070?fp_cot=cot_***. Replace **cot_ with the connect_token. The resulting URI may look similar to this example:
6

Follow the flow

Connect will present you with a set of pages that will let you share your tariff information. It automatically chooses the best route to discover your tariff based on the availability of provider APIs, data-sharing regulations and frequency of provider use within the FlatPeak base.
7

Receive and process callback

Once click Save button on Your Tariff Summary** screen, Connect will send the following to callback_uri you specified:
Example callback
https://webhook.site/4623e56fc5c1?fp_cot=cot_6587fa4362341be5b524de3b
8

Exchange completed Connect token for Location ID

Once you receive a callback and use connect_token as a reference, call the exchange-connect-token API endpoint to obtain a location_id that represents a permanent identifier of your customer’s address in FlatPeak. Store it in your database as a reference to the physical location of your customer’s property.
9

Subscribe to tariff lifecycle webhooks

After your customer completes the Connect flow, FlatPeak will automatically keep their tariff information up to date. If any action is required from the customer, FlatPeak will generate an event. You should subscribe to these events via webhooks and implement a communication flow to notify your customers and let them update their tariff connection if necessary.
10

Let customers view their tariff and change connection

Customers may wish to modify their tariff settings from time to time or when you notify them of a detected change (webhook). To support these scenarios, follow the Building a tariff settings page in your app guide to add controls that let them update or reconnect their energy account.
UI integration tip When embedding Connect into your app, launch it in a modal or a sheet iOS, Android to avoid layout issues—especially on devices with camera notches or cutouts. This ensures a clean, contained user experience without UI elements being obscured.
Next steps You can now query the FlatPeak API for your customer’s tariff data and access all other energy intelligence endpoints. Choose from two different integration paths for this step:

Use out fast-track planning and cost reporting endpoints

Get raw tariff and implement planning and cost reporting yourself