Native app or server-side Tutorial

Connect-headless works somewhat similarly to a chatbot: It provides you with JSON objects that you will use to build customer interface pages in your app; Once a customer makes an interaction with a page (i.e. selects their provider from a list) you will send their choice to Connect’s HTTP endpoint and immediately receive next JSON object to render in your app’s UI.

Understanding Connect-headless

Connect-headless (hereafter Connect) is an HTTP-POST service that uses JSON objects to carry the payload. As a developer, you can consider it to be a chatbot that uses pre-created pages (aka routes) instead of free text messages to build user flows.

Every time you send a request to Connect’s sole HTTP endpoint, it will respond with instructions to render a page where your customer will make a selection from a list of options or input new data. You will capture your customer’s responses and submit them to the same HTTP endpoint.

This flow continues for as long as necessary to discover or connect to your customer’s tariff. Once completed you will receive a permanent location identifier that you can use to query your customer’s tariff from FlatPeak API.

Follow the instructions below to learn how to implement Connect in your application:

Obtain a Connect token

We recommend that you implement this step in your back-end.

You need a connect_token to start a session with Connect.

Connect Tokens are single-use objects that identify and secure your user’s session with Connect. Every time you want to start a new Connect session for your customer (i.e. your app’s user), you need to create a new connect_token.

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.

Create a Connect token

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

Set callback_uri to any page that can accept callbacks. Our team likes https://webhook.site but you can choose any other service.

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",
"callback_uri": "https://webhook.site/4623e56fc5c1",
"postal_address": {
  "country_code": "GB"
}
}'

Run Connect-headless flow

We recommend that you implement this step in your front-end.

Once you obtained the connect_token, you can start exploring the Connect HTTP service.

Start session with Connect

curl --request POST \
  --url https://connect.flatpeak.com \
  --header 'Content-Type: application/json' \
  --data '{
  "route": "session_restore",
  "connect_token": "cot_65df3e949a785c52283026ec"
}'

Connect will respond with any of the following JSON objects, each representing the content of a page that you will render in your app.

You must implement all pages listed below and be ready to render them when requested by Connect. Continue reading to learn how it works.

Handling redirects & callbacks

Connect may also respond with an instruction to redirect the customer to an external web page where they will provide consent to share access to their energy supplier account with your application. This happens when DIRECT integration exists with the selected energy supplier:

Handling Redirects

Connect may respond with the session_redirect route. Usually, this happens when the customer needs to log in to their account at their energy provider’s website to give consent for you to access their tariff.

{
  "connect_token": "cot_6587fa4362341be5b524de3b",
  "route": "session_redirect",
  "live_mode": false,
  "data": {
    "redirect_url": "https://british-gas-uk.connect.flatpeak.com"
  }
}

You will redirect the session to redirect_url via HTTP-GET appending connect_token.

Example redirect (http)

GET /?fp_cot=cot_6587fa4362341be5b524de3b HTTP/1.1
Host: british-gas-uk.connect.flatpeak.com

You can append any other query parameter to redirect, for example, your internal session or a security key. They will be returned to you via callback later.

Handling Callbacks

Once you redirected the customer’s session to redirect_url you will soon receive a callback to the URI you specified when you created the connect token. It will have the same query params and payload that you appended to the redirect.

POST your response to Connect via session_restore route:

myapp://oauth-callback/flatpeak?fp_cot=cot_6587fa4362341be5b524de3b

Handling completion of Connect session

Once the Connect flow has been completed, Connect will respond with the session-complete route. Data payload will include your original callback_uri with fp_cot query parameter carrying the original connect_token.

{
  "connect_token": "cot_6587fa4362341be5b524de3b",
  "route": "session_complete",
  "direction": "IMPORT",
  "live_mode": false,
  "data": {
      "callback_uri": "https://webhook.site/4623e56fc5c1?fp_cot=cot_6587fa4362341be5b524de3b"
  }
}

Return your customer to other pages of your app and follow the next section to exchange connect_token to a permanent ID that you will use to obtain your customer’s tariff and use other endpoints of FlatPeak API.

Obtain IDs to access customer’s tariff

We recommend that you implement this step in your back-end.

Using connect_token as a reference, call exchange-connect-token API endpoint to get permanent identifiers that you will use to obtain your customer’s tariff.


`customer_id`	Identifies your customer in FlatPeak systems.
`location_id`	Identifies the physical location where energy is supplied under an agreement between your customer and their provider.

Store both IDs in your application’s database in reference to your customer and the physical location of their property.

Make requests to tariff rates API endpoint

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>'

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."
}

Shall you find it challenging to implement Connect-headless in your app or back-end, get in touch with our support team. We’d be glad to help!

Getting Started

Connect Tutorials

API Tutorials

Open source

Native app or server-side Tutorial

Understanding Connect-headless

Obtain a Connect token

Run Connect-headless flow

Obtain IDs to access customer’s tariff

Make requests to tariff rates API endpoint

Getting Started

Connect Tutorials

API Tutorials

Open source

​Understanding Connect-headless

​Obtain a Connect token

​Run Connect-headless flow

​Obtain IDs to access customer’s tariff

​Make requests to tariff rates API endpoint

Understanding Connect-headless

Obtain a Connect token

Run Connect-headless flow

Obtain IDs to access customer’s tariff

Make requests to tariff rates API endpoint