Native app or server-side integration

Understanding Connect-headless

Connect-headless is an HTTP API with a single endpoint that behaves similarly to a chatbot:

In this article, Connect-headless is referred to simply as Connect.

Your app initiates a Session: Your application begins new “chat” session with Connect by submitting a request containing a connect_token to a Connect’s HTTP endpoint.
Your app receives JSON Response object: Connect responds with a JSON object that includes all the information needed to build a page in your app, including supported user actions.
Customer makes a Selection: Your customer reviews the page and selects one of the actions, you submit their selection to the same HTTP endpoint using the original connect_token as session identifier.
Iterative Exchange: Connect returns the next JSON object in response. This cycle repeats until the customer’s tariff is identified and/or connected.

Planning your implementation

You implement all JSON page templates: To handle every possible JSON object you may get from Connect, you must implement 14 pages in your app, listed below.
Enable Connect to your app: To integrate Connect functionality to your application so your customer to access it when they want to connect their tariff, refer to Displaying Tariff Settings guide.

Starting new session with Connect service

Create a Connect Token

This step shall be implemented in your back-end.

Connect Token is a single-use object that identifies and secures your customer’s session with Connect service, for the duration of that session. To create it, make a request to create-connect-token API endpoint.

Start session

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

Now that you have a connect_token, you can start exploring the Connect HTTP service. Make a request to Connect the URL as per the example below:

An attempt to use a Connect token after it expires will result in token_expired error. See errors for more information.

Implementing Connect pages in your app

When you start a session with Connect service, it will respond with any of the following JSON objects, each representing the content of a page that you will render in your app:

When customer selects a provider with a DIRECT integration through FlatPeak, Connect will instruct you to redirect the customer to an external page where they can provide consent to share access to their energy account.

Handling Redirect

Connect will respond with the session_redirect route.

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 Callback

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 via the API. It will have the same query params and payload that you appended to the original redirect.

POST your response to Connect via session_restore route:

Your customer’s experience with redirects

Your customer will likely interact with only two pages - Login and Consent.

However, depending on how the provider implements the login process, the configuration of their account (such as having multiple properties supplied under one contract) and other factors, they may be presented with additional pages:

The actual look and feel may vary between providers as they develop and host the pages. The word [Brand] will always be replaced with your business name.

If the customer hasn’t logged in to their energy provider or selected a tariff from the library (e.g., if FlatPeak doesn’t have it or it’s missing), Connect will try to gather the tariff information by asking a series of questions, starting with the tariff structure.

On this page, the customer can choose from three options:

Option	Description
`FIXED`	Customer will be requested to input their fixed (flat) tariff rate.
`TIME_OF_DAY`	Customer will be requested to input their variable tariff rate.
`MARKET`	Connect will automatically detect customer’s market rate using their postal address. It will then provide the customer with an option to indicate what fees and/or surcharges they are paying to their provider on top of that rate.

Once the customer’s tariff has been captured, they will be shown its summary on the final page, where they can review, update, or disconnect it.

Page actions explained:

Action	Result
`SAVE`	Saves tariff and completes the Connect session.
`EDIT`	Restarts the Connect flow from the Provider Selection page.
`DISCONNECT`	Disconnects the tariff and completes the Connect session.

The tariff summary page has two versions, the choice of which depends on the tariff’s structure. Connect will automatically select the correct version of the page.

`FIXED` tariff

`TIME_OF_DAY` or other dynamic tariff

If Connect cannot instantly access the customer’s tariff, such as during a provider’s system outage, it will return this page.

Page actions explained:

Action	Result
`SAVE`	Saves tariff configuration and closes the page. Connect will continue to try to connect the tariff in the background.
`DISCONNECT`	Disconnects the pending tariff and enables the customer to go through the Connect flow again.
`DISMISS_DIRECT`	Disconnects the pending tariff and automatically skips the DIRECT option when the customer selects their provider.

When a customer clicks Save, Connect will immediately complete the session, and you can obtain the Location ID. However, Tariff Rates and other API endpoints will return error 422 (“code”: “pending_connect”) until FlatPeak’s backend systems can access the tariff; this can happen in a minute, an hour, or a day. If the tariff cannot be accessed for over 48 hours, FlatPeak systems will send a webhook tariff.fetch.failed

When Connect is unable to access the customer’s tariff, it will return to this page when you want to show your customer the tariff summary.

Page actions explained:

Action	Resumt
`RECONNECT`	Takes the customer to the Provider Selection Page where they can choose their current provider and reconnect the tariff.
`DISCONNECT`	Disconnects the tariff and completes the Connect session.

Completing the Connect session

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

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

Exchanging Connect Token for a Location ID

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 location where energy is supplied under an agreement between your customer and their provider.

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

If you find it challenging to implement Connect using this guide, get in touch with our support team. We’d be glad to help!

Introduction

Build with FlatPeak

Implementing Connect

Native app or server-side integration

Understanding Connect-headless

Planning your implementation

Starting new session with Connect service

Implementing Connect pages in your app

Completing the Connect session

Exchanging Connect Token for a Location ID

Introduction

Build with FlatPeak

Implementing Connect

​Understanding Connect-headless

​Planning your implementation

​Starting new session with Connect service

​Implementing Connect pages in your app

​Completing the Connect session

​Exchanging Connect Token for a Location ID

Understanding Connect-headless

Planning your implementation

Starting new session with Connect service

Implementing Connect pages in your app

Completing the Connect session

Exchanging Connect Token for a Location ID