This guide will walk you through the process of trying FlatPeak service for the first time.

​
1. Get a Dashboard account

Before you begin, make sure to create an account and complete onboarding. Once completed, you’ll be able to access your API keys.

Use test (sandbox) mode keys for your development.

​
2. Run Connect flow

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.

You can also use the FlatPeak-hosted version at https://connect-web.flatpeak.com. If you choose this option, replace http://localhost:7070 with this URL in the steps below.

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 bearer token to access FlatPeak API

  1. Go to the Dashboard API section to retrieve your Account ID and API Key. Use test (sandbox) mode key.

  2. Base64 encode the combination of account_id:api_key and make a request to create-a-bearer-token endpoint.

    curl --request GET \
  --url https://api.flatpeak.com/login \
  --header 'Authorization: Basic <base64 encoded account_id:api_key>'
5

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

Make a request to create-connect-token endpoint to obtain 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_web_uri": "http://localhost:7070",
  "callback_uri": "<any service that can receive webhooks>",
  "postal_address": {
    "country_code": "GB"
  }
}'
If you’re looking to prototype receiving callbacks (i.e. for callback_uri), we recommend using https://webhook.site, but you can use any other service.
6

Run the Connect 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:

7

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.

The fastest way to test the Connect flow is by using your own account with a supported energy provider and selecting that provider during the flow. If you don’t have access to a compatible account, contact support and we’ll help you get set up.
8

Receive and process callback

Once click Save button on Your Tariff screen, Connect will send the following to callback_uri you specified:

Example callback
https://webhook.site/4623e56fc5c1?fp_cot=cot_6587fa4362341be5b524de3b
9

Exchange completed Connect token for Location ID

Once you received a callback and using connect_token as a reference, call exchange-connect-token endpoint to obtain a location_id that represents a permanent identifier of a property address in FlatPeak. In the future you will store it in your database in reference to the physical location of your customer’s property.

curl --request GET \
--url 'https://api.flatpeak.com/connect/tariff/token?connect_token=cot_6587fa4362341be5b524de3b' \
--header 'Authorization: Bearer <token>'
10

Get tariff rates

You can now query the tariff-rates API endpoint to obtain tariff data.

curl --request GET \
--url 'https://api.flatpeak.com/tariffs/rates/loc_641b90b758fb8e6293716e40?start_time=2023-06-15T09:00:00Z&end_time=2023-06-15T13:00:00Z&include_tariff=true' \
--header 'Authorization: Bearer <token>'