​
Obtain a Connect token

You need a connect_token to start a session with Connect. Connect Tokens are single-use objects that identify and secure your user’s individual session with Connect. Every time you want to start a new Connect session for your user, you need to create a new connect_token.

1

Authenticate to FlatPeak API

To create a connect token you need to make a request to create-conect-token API endpoint. Learn how to authenticate to FlatPeak API, follow the authorization-guide.

2

Create a Connect token

Go to create-connect-token API endpoint and create a connect_token.

Our team likes https://webhook.site for callback tests but you can use something else.
curl --request POST \
--url https://api.flatpeak.com/connect/tariff/token \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"direction": "IMPORT",
"type": "COMMODITY",
"connect_web_uri": "https://connect-web.flatpeak.com",
"callback_uri": "https://webhook.site/4623e56fc5c1",
"postal_address": {
  "country_code": "GB"
}
}'

​
Run the Connect flow

1

Launch Connect-web in your browser

Launch FlatPeak-hosted version of Connect in your preferred web browser at https://connect-web.flatpeak.com and append connect_token you obtained in the previous step as the query parameter fp_cot. The resulting URI shall look similar to the example below:

2

Input a postal address to get a list of energy providers serving the area

Connect will present you with a screen where you will be asked to provide a postal address. This information is used to create a filtered list of providers (and their tariffs) that are available in the area. You can use your actual address or any other address you would like to test.

3

Follow the Connect flow

Connect will present your customer with a set of screens that will let them share their tariff information. Connect automatically chooses the best route to discover the tariff based on the availability of provider APIs, data-sharing regulations and frequency of provider used within the FlatPeak base. Route options include:

OptionDescription
DIRECTLogin to account with their provider and grant you access to read their tariff.
LIBRARYPick up their tariff from FlatPeak-maintained tariff library.
MARKETConnect automatically maps customer’s location with energy market rates.
MANUALInput information about their tariff via a series of interactive screens.

Depending on the route Connect has chosen for the customer, provider and tariff combination the customer may be presented with between 4 and 8 screens where they will first select their provider; then login to their provider account, pick their tariff from the FlatPeak-maintained tariff library or input their tariff through the assisted tariff process.

4

Connect redirects to callback_url

Once the customer completes the Connect flow, Connect will redirect their browser session to callback_url you specified earlier:

https://webhook.site/4623e56fc5c1?fp_cot=cot_6587fa4362341be5b524de3b&fp_status=success

​
Obtain permanent ID to access customer’s tariff.

Using connect_token as a reference, call exchange-token API endpoint to obtain location_id that permanently identifies of the physical location where energy is supplied under an agreement between your customer and their energy provider.

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

​
Make requests to tariff rates API endpoint

1

Requesting tariff rates

You can now make requests to tariff-rates and other API endpoints using location_id as a reference.

curl --request GET \
  --url 'https://api.flatpeak.com/tariffs/rates/{id}?start_time=2023-06-15T09:00:00Z&end_time=2023-06-15T23:00:00Z' \
  --header 'Authorization: Bearer <token>'
2

Handling pending tariff connection

If FlatPeak background service is unable to immediately access your customer’s tariff (for example if energy provider systems are down or if FlatPeak provider integration is unable to parse the tariff) you will receive a 422 error response from the API.

Continue to make the API calls, the error will usually clear itself in minutes. If this does not happen, FlatPeak engineer will resolve the issue behind the scenes; no action is required.

{
  "object": "error",
  "type": "api_error",
  "live_mode": true,
  "time_created": "2022-01-24T14:15:22.003",
  "code": "pending_connect",
  "message": "Connect is processing link to tariff source."
}

Was this page helpful?

Plan your integrationSingle-page web app